Code Example Launchers | Developer Deep Dive

Code Example Launchers | Developer Deep Dive


[MUSIC PLAYING] Hi. My name is Matthew Roknich,
developer evangelist at DocuSign. I’m here today with Larry
Kluger, who is a former product manager, program manager,
and now lead developer evangelist at DocuSign. Larry, welcome to the team. Thank you, Matt. So Larry, we’ve known each
other for quite some time. But for the interest
of the viewers, can you talk a bit
about your background? So I’ve been in tech
for quite a while now. I started off as a
engineer doing software for Xerox in Palo Alto. After that, I worked
for Sun Microsystems. I was working in England
as their software product marketing manager. And then I was at Remedy
and some other companies. And now, I’m here at DocuSign. It’s great to be here. Great. So your new role as lead
developer evangelist, what is your main focus? My focus is to help
out our developers. So that includes a number
of different projects, including the
tracking to make sure that our developers’ questions
are answered on Stack Overflow. Helping you and our colleagues
out at trade events. Writing blog posts, continuing
my work with examples, all these different projects
to help developer community. Sounds great. So you’ve been at DocuSign
for roughly four years. What’s that one thing that
gets you out of bed every day to get to work? So what I love about
DocuSign is how our customers love DocuSign. And that includes
our IT customers, who develop new software that
integrates with our software. And I enjoy working with them. They build great integrations
with our software, and it’s fantastic
to help them out. So Larry, in your past
role, you spent quite a bit time working on code
examples and sample apps. Rumor has it that today, you’re
going to be talking about one of your newest projects,
the code example launcher. Is that correct? Correct rumor. Yes. Excellent. Can you talk a bit
about what that is. What is the code
example launcher? Sure. So I worked on the examples
over the past year, that I did over 14 or more for
each of our major languages. And I realized, as I
was working on them, that we needed to have a
framework to run the examples. So for each of our languages,
for C#, PHP, Python, Node, Java, and Ruby, we wanted to
have not just the examples, but also a way of
running the examples. And that’s what the
code launchers do. In addition to
running the examples, the code launcher
serves as an example of how to do authorization
code grant, which is the OAuth technique that we recommend
when someone is they’re present, when the
user’s present. And finally, the launchers
enable us to easily add new workflow examples. And we plan to have many
more coming over this year, and into the future. Love it. So which frameworks,
libraries, etc., did you use to build
your launchers? Right, good question. So what we did is, for
each software language, we looked to see what’s a
commonly used software stack that’s well-supported and has
the features that we want, and most importantly is popular. So for C#, we use
C# .NET Core MVC, which is what’s recommended by
Microsoft for a web app that you build from newly
build these days. For Node.js, we’re
using Express, which is a very
commonly used web system for Node.js software. For Ruby, it was easy. That’s Ruby on Rails. So we use these
different stacks. And then for each
stack, we also look to see which would
be a good library to use to demonstrate how to do
OAuth Authorization Code Grant. To start again with C#, the C#
.NET Core MVC platform includes a what they call security
library that supports OAuth we use that. With Java, we used what’s called
Spring Boot as the framework. And that has as an
optional component what’s called Spring Boot Security. And that supplies the OAuth. For Node.js, we use a
very popular library called Passport. So we put all these
things together, so that these sample
applications and the launchers are not just ready to use,
but are also ready to be run. So they include what’s called
the package configuration files, so that the SDK and
other libraries are pulled in automatically, and all
is ready to work right out the box for the developer. Great. So can we see an example of
the PHP could launch your live? My pleasure. Excellent. Let’s do it. OK, Matt, so what
we’re going to do is the PHP authorization
grant launcher. We started here on the
DocuSign page of GitHub. You can see the URL right here. And this lists all of our
different repositories. The easiest way to
find the right one is to put it here under
Find a Repository. So the eg-03 are the launchers
that we want to focus on. And you can see,
there’s seven of them. Now, we may be renaming them
in the future, in which case, again you’ll look here,
you’ll get the right name. The one we want is PHP. So it’s down here. So we just click on that. Here’s all the information,
and also the README. What I’m going to do is really
go through the README step by step. And so you’ll see exactly how
we install it, configure it, and get it running. So the first part
of the README me is talking simply about
an introduction and all the different examples
that it includes. It includes the
authentication with DocuSign, the Authorization Code Grant. And that includes these numbered
workflow examples 1 through 18. So then we move on to
the installation steps. And the first thing is, you need
a DocuSign Developer Sandbox. I have one of those,
DocuSign Integration Key. And I’m going to show
how to create that. And then in particular,
the Integration Key needs what’s called
a redirect URI. And that’s what this
is talking about here. And I want to talk about that
very carefully, about each step that we go through. The issue with the
redirect URI is that we need to understand
what is the application URL of the launcher,
once we have it installed in our system. And I’m going to be
running it locally here. And so I’m going to go
through this step by step, and in particular, what
is the public directory of the example. So I’ve made a little chart. And on my computer, I’ve
set things up so that http://localhost is the same
as the internal file location of /Users/larry.kluger/www. But how you have your web server
set up on your own development machine might be different. But you can see that local host
is what matches up with www. So then I’m going to install the
example on the www directory, as eg-03-php-auth-grant
on the www directory. And then the public
directory of the example is simply the public part. So I add /public. So now we’re at this point
here, this whole row here. So then we need to
figure out what’s going to be the URL
for, in particular, the public directory. And what we do is we put
the two parts together. So localhost,
remember corresponds to up through the www. And then all this next part,
then we add onto the URL eg-03-php-auth-grant/public. So therefore, remember back,
the README told me that we need to redirect URI to be indexed
index.php/ds_callback. And so then, that means that
the entire redirect URI, that’s this magic thing that we
need for the integration key, is going to be this
long thing right here. So now we have that, we can
create the integration key. So the way we create the
integration key is we go to DocuSign. And here we are. I’m logged into DocuSign. We go to the admin
tool, just like that. And then on the
bottom left side, we’re going to go
to the API and keys. That’s down over
here, API and keys. We click that. Now, I’ve already got the
integration key created. It’s, in fact, this first one. And so if I now
edit it, we can see, here’s the integration key. And here are the redirect
URIs, including right here. This is the one we just
discussed, localhost/eg-03- php-auth-code-gr
ant/public/index ?page=dscallback. So that’s what the README– that’s what we figured out from
the combination of the README and my own particular
installation of a web server on this machine. We also have the secret key. I have the full secret key. This is just showing the
last four digits of it. And this key pair stuff is not
needed for authorization code grant. OK, so let’s go back now and
look again at the README. And we’ve got this
taken care of. We’ve got PHP. We know the name of a
signer, all that good stuff. So now we’re at the
installation steps. So we’re going to do is download
or clone this repository, in this case, to my
local machine I’m using for development. The way we do that is we go all
the way to the top of the page and click Clone or Download. And I’m going to just
say Open in Desktop. And I’m going to clone again. And it’s done that now. So now it’s been downloaded
to my local machine. As an alternative, I
could have download the ZIP file and unzipped it. I just used GitHub Desktop. OK, so the next step, if we
again go down into our README, into the installation
steps right here, is that I need to
run composer install. And that’s using
the package manager that’s commonly used with PHP
to install all the dependencies. So we go into our terminal
window, and we go to eg-03-php. There we go. And then we’re going
to do composer install. And this is pulling in all
the libraries that are needed. In this case, as it says
here, it’s loading from cache. But the first time,
what will happen is, it will load from the
network from various sources, file servers out
there on the internet. And this all happens
automatically. And in particular, it also
loads the DocuSign SDK. So everything is all
taken care of for us. OK, let’s see what
the next steps are. Next is to update the file
ds_config with the integration key and all the other settings. So let’s look at that. We will open up an editor. I’ll use this one, and
we want to say Open. And then we want to
go to www and the php. There we go. We open that. And let’s look at
what we’ve got here. So I’m looking at
ds_config file. This is the way it comes
from when you download it. Let me make it a
little bit bigger. And what you’re going
to do is insert– replace all of this
with the client_id, with the client_secret,
all that kind of stuff. Right here, the
app_URL is going to be the URL of the application
of the public directory. And remember, we figured
that out earlier. And when you update
these values, you don’t want to
leave the curly braces. So this would become
http://localhost, etc., as we figured out. Now, as they say on
the cooking shows, I happen to have one
that’s already prepared. And so I’m just going to
copy that because it’s a lot of setting. So I’m going to copy– I call it credentials,
and then php. And the ds_config
that’s there, I’m going to copy it to
where we are right now. And so now that that’s all been
updated, let’s see what’s next. The web server, in our
case, is all set up. So it will serve the files that
are in the public directory. And remember that you had
to set the integration key with the redirect URI. So we’ve already done that. So now let’s test it out. So we go to localhost. And let me refresh the page. And remember, on my
development machine, I’m looking at
php-auth-code right here. So we look at that. Then we want to look at
the public directory, which is the actual location
where a user would come to look at the front
page of the launcher. So the good news is
everything worked. Here we are, the front
page of the launcher. And the way this works– I thought that was
logged in, I guess from previously running it. So this is the way that
it will normally look. It says Welcome! And then it lists all
the different examples. So we don’t have time to
go through all of them. I want to just point out
maybe one or two of them. So the first one that
I’ll show is very popular, and that’s Embedded
Signing Ceremony. So I do that by
just clicking here. And I’m being asked
to authenticate, so I click like that. And I’m now completely
authenticated. The reason I was authenticated
automatically like that is I was already logged in to
DocuSign on another tab. I can demonstrate how that would
work if I was not logged in. So here I am on my DocuSign tab. Remember, we were
using the Admin tool. So I’ve logged out there. And now, here we are. Let’s try this again,
Embedded Signing Ceremony. It asked me to authenticate. And it this time asked me
to log in, because I’m not logged in on a different tab. So I log in. Now here, at DocuSign
we use a single sign-on. So that’s what we call
Use Company Login. And so that will go through
our single sign-on system. So now again, we’re
authenticated with DocuSign. Here we are. I can change my signer email
and signer name if I want, or I’ll just hit Submit. Remember that this
is embedded signing. So up comes the Embedded
Signing Ceremony. And it knows who I am. I’ve done this before. And after we finish the
Embedded Signing Ceremony, we’ll go back to the launcher. So this is now demonstrating
that after you have your web app do embedded signing, you
come back to your own web app and you get the information that
the person’s finished signing. Let’s go back to the home page. Let’s do the second one. Now, what I also
want to point out is, when you do any
of these workflows, it gives you a little blurb
about what the workflow does. It tells you the API method,
and you can click on this to go over to the Dev Center. And this is all the details
on that particular API method. And also, it gives
you a direct link to the source of what this
example workflow is doing. So in this case
here, we click here. And this is the source. And what you want to look for is
what we call the worker method or worker function. And that’s right here. So here’s this function worker. And this goes through the
steps of, in this case, creating an envelope with
three different documents– documents 1, 2, and 3. Putting that together,
sending into DocuSign, and getting back the
result. So that’s what happens when we run this. And the signer email is preset. For the CC, you need
to put something in. I’ll use that email
and hit Submit. And what we’ll get back
is simply the Envelope ID, because this example
is sending what we call a remote signer via email. And we’ll get back
to Envelope ID. There it is. So the last of these
many different examples that I want to show is, I want
to point out example number 10. It’s a little bit
different from the others, because example number
10 does not use the SDK. Example number 10 shows
how to send documents to DocuSign without
first encoding them using base64 encoding. When you use the SDK,
all of the documents are base64-encoded,
which is fine, but it adds a lot of overhead. And if you have a very
large document, more than let’s say 10 megabytes
or something like that, then you probably want to
send it in binary mode, and not have the overhead
of base64 encoding. So this example, example number
10, shows you how to do that. The user interface
is the exact same as what we did before the Signer
Name, the Email, the CC, all that kind of stuff. When we hit Submit,
everything is the exact same. The only difference is what’s
happening on the inside. And we’ll look at
the source here. On the inside, what’s happening
is that this source shows you– first we go down to the worker. Right here, the worker
file, the worker method. And this is showing
you how to put together what’s called a multipart
MIME request to DocuSign that has all these different
parts to it, including the JSON and the different
documents– in this case, three different documents. And the benefit of
doing it this way is that you can send the
documents in a pure binary mode. The downside is that
this is more complicated than using the SDK. That’s why we recommend
using the SDK normally. But in certain
circumstances, you want to call DocuSign, and send
the documents in binary mode. And that example shows
you how to do it. Two last things to say. One is that, as I
mentioned earlier, the example launchers show
how to do authentication. And so you can look
up the details. In this case, how to do with
authentication using the PHP OAuth 2.0 client package. And that’s built into
this demo launcher. And then the last thing is
that this set of examples is the same set used
in our other launchers. So if you want to see how to do
Embedded Signing Ceremony with Java or C# or Node.js, or any
of the other example launches we have, that will all
be example number 1. And in this case, PHP, we’ve got
18 of them– except number 14, we’re going to do in the future. In many of the others,
sometimes we’ve only gotten up to the
first 14 are implemented. But all this is coming
along, and there’s already lots of examples to help
out our developer customers. This is excellent, Larry. Very, very good job. Love this stuff. One quick question
as a follow-up. For any developers
that are struggling to get started with
our APIs or SDKs where would you recommend
they get started? So the first place for
some of questions to go is Stack Overflow. OK. And be sure to use the
tag DocuSign API, which is all one word. You can either go to
Stack Overflow directly, or another good
option is to just use Google to search for an
answer to your question. We’ve got over 3,000
questions on Stack Overflow, and so the answer is
generally available. If you notice an issue with one
of the launchers themselves, or if you want to propose
a new workflow example, then you can, again, use
Stack Overflow if you want. Or, probably better,
go to GitHub, and use the Issues page
for that repository. And then also, we’ve got a
lot more help for people, and information for people. One is the series of
webinars that I host called the API Office Hours. And you said that you’ll put
the registration link for that under our video, once
we have that done. And those are really the
main places for help. Excellent. So as Larry mentioned, if you
are interested in the next API Office Hours, the
link to register will be in the description. But that’s all
we’ve got for today. Larry, thanks so
much for being here. A pleasure. Thanks. [MUSIC PLAYING]

Leave a Reply

Your email address will not be published. Required fields are marked *