Transaction admin API needed

[OpenESignForms]

Need an API for systems that integrate deeply and need more information and control over transactions.

The transaction template will get a new permission for "Admin API" that would be similar to the Update API permission. The ESFLOGINUSER specified must belong to a group indicated in that permission for the transaction template that matches the transaction specified by ESFTID.

At a high level, the external app will do an HTTPS POST request to an URL like https://esign-contracts/WEBAPP/tranadmin/... and the response will be XML with the answer or an error. The first 3 params must always be present as they identify the requester and the transaction.

We'll have a standard success|error flag that is returned in all XML responses. Unauthorized or invalid requests would likely be rejected with HTTP status codes other than 200 and would not have an XML response. For example, http status 403 (FORBIDDEN) is returned if not authenticated; http status 404 (NOT FOUND) if the ESFTID or specified documents/parties are not in legal values or the transaction cannot be found; http status 503 (SERVICE UNAVAILABLE) for system errors;

Params shown in [brackets] are optional ways to limit what is returned to only those that match.

XML error responses would only be returned if the ESFLOGINUSER is authenticated with permission to make the call and the ESFTID points to a valid transaction.

Request URL: https://esign-contracts/WEBAPP/tranadmin/GetStatus

Params (in practice, all must be URL encoded but omitted here for readability): ESFLOGINUSER=apiuser@example.com ESFLOGINPASSWORD=secure ESFTID=transaction-uid [ESFDOCUMENT=documentname] -- if missing or no value, assumes all documents [ESFPARTY=partyname] -- if missing or no value, assumes all parties

Response XML: Would include the current transaction status, status text, last updated timestamp; the pickup URL, email address, last accessed timestamp, party name and status for each party; and for each document handled by the party, the document name, status, last update timestamp, esign IP+host address and esign timestamp (if esigned).

Errors would be for no such document, no such party.

++++

Request URL: https://esign-contracts/WEBAPP/tranadmin/GetDocumentSnapshot

Params (in practice, all must be URL encoded but omitted here for readability): ESFLOGINUSER=apiuser@example.com ESFLOGINPASSWORD=secure ESFTID=transaction-uid [ESFDOCUMENT=documentname] -- if missing or no value, assumes all completed documents [ESFPARTY=partyname] -- if missing or no value, assumes latest party to have completed the associated document FORMAT=HTML|PDF|XMLDSIG|PDFMERGE -- HTML is the native document format; PDF is the HTML document converted to PDF; XMLDSIG is the XML digitally signed HTML; PDFMERGE is all documents merged into a single PDF (so makes most sense for a particular party or for "latest party" -- it would be allowed, but odd to request a merge of the same document across parties) [INCLUDEDATA=XMLDSIG|XML] -- if missing or no value, the document data (name-value pairs for fields in the document) would not be returned. XMLDISG would be the XML digitally signed data; XML would just be the data in XML format.

Response XML: Would include the document status, last update timestamp, and optional document snapshots (if completed) with optional esign IP+host address and esign timestamp (if esigned) based on filters. If the specified document/party has not been completed, the document status will indicate this and there will be no corresponding document itself returned (as there is none).

Errors would be for no such document, no such party, unexpected format, unexpected data request.

++++

Conceptually, this API request is not really needed as you could do a standard UpdateAPI call for the transaction id with an event name that would trigger any actions you want, including sending an email to any party or canceling the transaction, etc. as defined in the package's custom logic.

Request URL: https://esign-contracts/WEBAPP/tranadmin/RenotifyParty

Params (in practice, all must be URL encoded but omitted here for readability): ESFLOGINUSER=apiuser@example.com ESFLOGINPASSWORD=secure ESFTID=transaction-uid [ESFPARTY=partyname|email address] -- if partyname includes an '@' symbol we'll assume it's an email address, but more typical to be a partyname; if omitted we'd renotify all currently active/retrieved but not yet completed parties (normally this is only a single party). [TRANSFERPARTY=someuser@example.com] -- if present, would attempt to do a "transfer party" using the new email address before sending out the email renotification.

Response XML: Would include the the party name, email address, last accessed timestamp, status and pickup URL. Of course, an email renotification would also take place. When a party name is specified and that party is configured with a To Do Group with 'notify all To Do Group', multiple emails may be sent out to all members of that group. If an email address is specified for the party, multiple parties could be renotified and returned if more than one party used that email address. If a transfer party param is specified and the email address matches the current party email address, no transfer will take place (and not an error). If a transfer party param is specified but the party is not active/retrieved, no transfer will take place (and not an error).

Errors would be for no such party, party has no email address/todo-group associated with it, party has no email template assigned to it. In general, to notify a party, the party must belong to a To Do Group or have an email address, and the party status must activated, retrieved or completed.

[OpenESignForms]

Special thanks to the International Computer Consulting Organization (ICCO) for sponsoring this API's expedited development.

[OpenESignForms]

This features is included in the 15.8.23 release.