Tuesday 31 January 2017

Oracle APEX and DocuSign part 2

APEXOfficePrint and DocuSign part 2

Sign your AOP documents

Integration with AOP, APEX and DocuSign


Now that we covered the basics we are ready to try it using APEX and AOP.

For those who missed the intro, it can be found here.



Today's post is all about REST APIs and RESTful services. To be able to run this on your side you will have to configure your site to use reverse proxy for example to let DB assess DocuSign API urls.

The end goal is: we generate a document in AOP, send it to be signed then pick up this signed document and store it in DB table.

To shorten the story I will assume that my AOP document is already generated and stored in DB table.

If you had a look at DocuSign documentation you will see that there are heaps of them available and now is all a matter of putting them together before letting APEX run the show.

Let's look at:
DECLARE
l_clob clob;

BEGIN
apex_web_service.g_request_headers(1).name := 'Content-Type';
apex_web_service.g_request_headers(1).value := 'application/x-www-form-urlencoded';
apex_web_service.g_request_headers(2).name := 'X-DocuSign-Authentication';
apex_web_service.g_request_headers(2).value:='{                 "Username":"yourdocusign@address",
"Password":"yourpassword",
"IntegratorKey":"yourIntegrator key" }';
l_clob := apex_web_service.make_rest_request(
p_url => 'https://demo.docusign.net/restapi/v2/login_information',
p_http_method => 'GET'
);
-- Display the whole document returned.
dbms_output.put_line('l_clob=' || l_clob);
END;
/
This is a basic call to DocuSign. Once you get this going you are all set. What we do here is make the call and return your login information. Nothing more.

In similar way in our next step we send the document to an email address using POST => https://demo.docusign.net/restapi//v2/accounts/YOUR_ACCOUNT_ID/envelopes/

Example of the code
....
begin
/*generate the AOP document and store it in a table*/
--take this document and send it to be signed
select output_blob
into l_blob
from your_table
where id = xxxxxx;

l_clob := apex_web_service.blob2clobbase64(l_BLOB);
l_body := '{"status": "sent",
"emailSubject": "Request a signature via email example",
"documents": [{
"documentId": "1",
"name": "contract.pdf",
"documentBase64": "';

l_body := l_body || l_CLOB;
l_body := replace(l_body, chr(13) || chr(10), null);
l_body := l_body || '"
}],
"recipients": {
"signers": [{
"name": "YOUR NAME",
"email": "youraddress@xx.yy",
"recipientId": "1",
"tabs": {
"signHereTabs": [{
"xPosition": "25",
"yPosition": "50",
"documentId": "1",
"pageNumber": "1"
}]
}
}]
} ,
"status": "sent"
}';

apex_web_service.g_request_headers(1).name := 'Content-Type';
apex_web_service.g_request_headers(1).value := 'application/json';
apex_web_service.g_request_headers(2).name := 'X-DocuSign-Authentication';
apex_web_service.g_request_headers(2).value := '{ "Username":"yourdocusign@address",
"Password":"password",
"IntegratorKey":"Integrator key" }';

l_result := apex_web_service.make_rest_request(
p_url => 'https://demo.docusign.net/restapi//v2/accounts/YOUR_ACCOUNT_ID/envelopes/',
p_http_method => 'POST',
p_body => l_body);

dbms_output.put_line('l_result =' || substr(l_result,1,500) );
END;
....
OK if you got this far means you got an email in your inbox saying document is ready to be signed.

Key problem now is how to get this document back to the database?

There is a nice thing called webhook. This give ability to DocuSign to talk back to the sender sending messages and documents once certain events happen.

How do we configure and use one?

There are two ways manual and automated. An easy way is to configure a Connect method for envelope completion status. To do this you create a Connect entity under you DocuSign admin console. This process is well documented and I will assume you will be able to handle it.

Very useful tip here for testing your webhook calls is using https://requestb.in

Here you can log you calls and make sure system is triggering them before you jump to APEX and start on implementation.

The second manual method is what we want to use for our APEX REST callbacks.
Before going into details see it in action:


via GIPHY


Full video - here.

In third post we will request a signature, sign it and finally download it into DB all from APEX application.

Thanks,
SLino


Saturday 21 January 2017

Oracle APEX, APEXOfficePrint and DocuSign

APEXOfficePrint and DocuSign

Digital Signatures for your docs

Give it a try you might be surprised


For few days now I have been playing with DocuSign. 
 

What is DocuSign and what it is for? Ever needed to implement a Digital Signatures in your project reporting. This is where these guys can help. Providing different services depending on your budget and needs. Please check out their website for further info.

Why? Ability to digitally sign your documents is a powerful thing and at some point we all may need something like this. Since I had some time to dig deeper I decided to try it out. Plus there is really decent amount of documentation available and everything you need is exposed through APIs which makes it perfect to integrate with ApexOfficePrint.

In this first post I will concentrate on what is needed for you to start using it in your APEX applications. 

First step is to register an account with DocuSign. Once this is sorted then you realize there is a developer account too (called Sandbox) so you create one for your self. 

Ok cool, now what next?  

 

Now you can configure your settings and update your signatures that can be used in your documents. 

Next step is to try out how basic documents and templates work. I will leave this bit to you as there are many demos and videos online that are very clear and helpful. From this perspective guys did a good job.

Bottom line of the story is you can create your documents upload it here, edit it by adding digital signatures to them that can then be sent out to different people to sign your documents. There is an option where you can create templates etc but I want to concentrate to what is important to all of us - integration with APEX and in this case APEXOfficePrint. 

Once you gave it a try creating and sending your first document using DocuSign UI it is time to look at their APIs. This gives you ability to create, sent and manage all your documents through a web service calls. Of course this is what we all are after.

Best place to start is API website. Here you will find everything needed to implement this into you PL/SQL calls.

Few things we need to know are: 
Account ID, Integrator Key, your registered email address and password. 

Where to find these?
Account ID is hidden behind you user account icon in top right corner.
     
It should be just under your details or sitting under PLAN section once you login into your admin account.

If you log into your regular account you will also get an account ID but these can not be used for APIs (at least I think so haven't tested it myself).

Integrator Key can be found under API and Integrator Key link. 
Now that you got all of these you are ready for you first API test.

To help out here there is REST API website. If you enter you details on top of this page you will be able to see few of them in action. 

In second post I will share some lights how we can do all of this from APEX apps and integrate this with APEXOfficePrint.  
 
Thanks,
SLino