#FeatureBlog - 19.4 - SOAP and Swagger (based REST services for Library projects)

#PreviewBlogs 2019.4 - SOAP and Swagger services for Library projects!

Please provide your valuable feedback about this feature!

New features are awesome! :slight_smile: This is why we wanted to get your thoughts on SOAP and Swagger-based REST services for Library projects, which was introduced in the latest version 2019.4. Consuming web services has never been easier!

Update on Cloud API authentication

Due to the platform.uipath.com becoming a cloud service, the API changed a bit. Please follow this bit of documentation for an official piece of documentation. You can also go here for a make-shift process that will do all important bits for you:

The only functional difference is that after you go through the steps in the documentation, you will need to use two headers to authenticate instead of one bearer token.
On how to do it in services, please see my post with a screenshot here:

How it works and why would you need it?

Have you ever tried to consume a SOAP or Swagger-based REST service and were struggling to do so in Studio? Long hours of constructing your HTTP Requests are over. With this new, simple and extremely useful addition of Services to Library projects, you are now able to seemingly integrate those in your projects.

Let’s have a closer look how useful it can be!

Let’s build a custom Library and then use it!

Our plan will be simple:

  • build custom library in Studio to handle Orchestrator API request
  • use our custom library to start an Orchestrator process via API request

Let’s go!

Creating new Library with a New Service

  1. Open Studio and start a new Library project


    Don’t forget to give it a nice name and description.

  2. Now, you will see a new option to create a New Service. This can be done either from the Ribbon or by right clicking the Services field in the Project settings:

  3. In the new window, type this URL into the File or link field (you can type any URL that points to any service description as long as it is a WSDL or swagger file). We will use the Orchestrator API swagger url:

    https://platform.uipath.com:443/swagger/docs/V2
    

    Click Load. It will take some time to load our Orchestrator API, but it will be well worth it!
    image

  4. When it loads, you will see all available end points of this service. At this point, you can also change the name of the Namespace for your New Service. In our case, it will be OrchestratorAPI:

    Now we can click Save to add our New Service. You can immediately see that it was added in the Project pane:

    image

    Now, let’s use it to build our workflow!

Building a library activity

Let’s build an activity that will start a new process by taking a few arguments:

  • Orchestrator credentials
  • Process Name
  • Robot Name

Let’s begin!

It is important to think what we are trying to achieve and what will be needed. To perform a successful API call to Orchestrator, we will need to:

  • authenticate our session to get a bearer token
  • get the robot id for the requested robot name
  • get the process id for the requested process name
  • start the process

To do so, we will make use of these four Orchestrator API endpoints:

If we were building a bigger project, we could create a separate workflow for each API call to keep things modular by having four library activities. However, for this example we will create one workflow which will contain four sequences for each API call.

At last, let’s go to Studio and make it happen :slight_smile:

  1. Let’s first add a new flowchart, rename it to something appropriate and then delete the default one. Your Process pane should look like that:

    image

  2. Then, let’s create sequences for every API call we want to make:

  3. Just to be sure all will work nicely, let’s also add the namespace of our service to the workflow, like so:

    After a click, it will be added to the list:

  4. Now, let’s assign all necessary arguments:
    We will need these 6 arguments:

    Argument Direction Argument Type Description
    in_TenantName IN String Orchestrator tenant name
    in_Username IN String Orchestrator username
    in_Password IN String Orchestrator password
    in_ProcessName IN String Name of the process to be started
    in_RobotName IN String Name of the robot which should run the process
    out_Status Out String Returns whether API call was successful

    It should look like this:

  5. Now, let’s edit the Authenticate sequence first:
    We need to add an activity for our API endpoint from the activities list:

    image

    Even though the activity looks a bit intimidating, we only need to worry about these two variables and its values:


    LoginModel
    and
    Response

    The easiest here is to use the CTRL + K shortcut in each field and create a variable of the respective type:

    We also need to remember to initialize this new variable like so:

    new OrchestratorAPI.LoginModel
    

    With that done, let’s create a sequence to initialize and assign values to the required fields. We can use Swagger for reference:
    image
    Here’s how it should look like:

    At the end, we will want to assign the bearer token that will be returned by the Authenticate activity to a variable available for other sequences. Let’s call it a bearerToken and set its scope to our flowchart:

    Then, let’s assign the output of our Authenticate service activity like so:
    image
    The authenticate sequence is now completed :slight_smile: Let’s complete our other sequences!

  6. Let’s continue with the Get Robot ID sequence next:

    In this case, it is a lot simpler. Simply drag and drop the GetRobots service activity, and then create the response variable with CTRL+K.

    Then, we should add this filter to its properties:

    "Name eq '" + in_RobotName + "'"
    

    Authenticate the call with our bearerToken:

    image

    And create another variable for the flowchart scope that will store our Robot ID. It all should look like that at this point:

  7. Next sequence, Get Release ID (thus our process name), is really similar to Get Robot ID and should look like that:

    The syntax for the filter would look like that here:

    "Name eq '" + in_ProcessName + "'"
    
  8. Lastly, our last sequence should combine the efforts and launch our process :slight_smile:

    We will have a bit more work here due to the specifics of that API call. Here’s how most of the flow should look like at the end:


    And this is the order to achieve it. Most of it revolves around the swagger definition of this API call:

  • First, we will initialize the object so that we can modify its values:

    image

    startJobsStartJobParameters.StartInfo = new OrchestratorAPI.StartProcessDto
    
  • then assign all the values necessary to launch the process:

    image

    startJobsStartJobParameters.StartInfo.RobotIds = {CLng(robotID)}
    startJobsStartJobParameters.StartInfo.ReleaseKey = releaseID
    startJobsStartJobParameters.StartInfo.Strategy = 1
    
  • lastly, we will start our job :smiley:

    Don’t forget to initialize your StartJobParameters variable as well:

    startJobsStartJobParameters = new OrchestratorAPI.StartJobParameters
    

  • and assign the state of the job as our output variable out_Status:
    image

    out_Status = startJobsResponse.Value(0).State.Tostring
    

    Let’s add one more write line activity and see if it all works!
    image

    Aand… RUN! (F5)

    As you can see, the process is not pending and will be launched the next time Robot sends a heartbeat to Orchestrator!
    image

    Here it is:
    image

Now we can publish our library project and run any job we want by simply providing just a few arguments!

Feel free to go through the entire project yourself and see it in action yourself :slight_smile::
OrchestratorAPIExample.zip (310.0 KB)

That’s it for this #PreviewBlog

For more information, you can also check our documentation of this feature available here.

Please provide your valuable feedback about this feature! Our product team is hungry to build upon the basic functionalities so feed them your ideas :slight_smile:

Don’t be shy, click on image below and tell us what you think!

As always, thank you for reading and happy automating!

20 Likes

Hi @loginerror,

I have followed the above steps, but i am getting the below error in Get Release ID sequence, Get Releases activity is working fine but not able to extract Release ID.

The expression used is getReleaseResponses.Value(0).key.tostring

And there is no intelligence is shown for Key method after Value(0)

image strong text

1 Like

Hi @anil5

It’s most likely due to the in_ProcessName not having the correct value for filtering.

Just as an example, this is how it should look like:

And this is how it looks in Orchestrator:

Thus, the in_ProcessName is actually ProcessName_EnvironmentName

Please let me know if it works then :slight_smile: (and I’ll update the post a bit to reflect that a bit better)

Thanks a lot for testing it! I know it’s not the shortest nor simplest blog out there :slight_smile:

1 Like

Hi @loginerror,

Indeed the issue was with the argument in_processName and after i changed accordingly ProcessName_EnvironmentName the workflow works perfectly and was able to run the job.

This is really cool feature :slight_smile:

2 Likes

Hi @loginerror,

this is a cool feature and I was able to run a process from orchestrator as per the guidelines and special thanks to @anil5, for reminding me to check this new feature and suggesting me in putting the process into work(to be precise helping me).

UiPath always puts community in front and thanks for that.

Regards,
Pavan H

4 Likes

Hello LoginError,

That is an awesome feature. This is really handy if an program expose a wsdl or a swagger-definition which will otherwise be automated through the gui.

May I`m allowed to write a littlebit technical?

In speak of the swagger-definition.

With the use of codegen tools like swagger-codegen may it is possible to add a security definition to the swagger-definition so theses tools can benefit from it?

My current modified definition looks like this:

  "securityDefinitions": {
    "Bearer": {
      "in": "header",
      "type": "apiKey",
      "name": "Authorization"
    }
  },
  "security": [
    {
      "Bearer": []
    }
  ],

The original looks like this:

  "securityDefinitions": {},
  "security": [],

At the moment I have to download this definition manually, add theses lines of json to the definition and run swagger-codegen to produce usefull code for my little self-developed csharp apps.

Adding theses lines to the definition would result in my case in allowing me, and of couse other developer, to simply set an “apikey” which would be consumed by restapi-frameworks. Theses frameworks will then automaticly exposed this key as an http-header like this: “Authorization: Bearer {JWT}”. And I also haven´t to do the download with every new version manually :slight_smile: . Without these lines you have to add the Bearer Token to the header for every single request, which can be nasty.

I hope my english isn´t to bad to understand and I hope it is usefull to improve UiPath futher.

If requested I can also post this in the Idea Section.

Best Regards
Mario (Lunk)

1 Like

Hey @Lunk

Thank you for your suggestion. I added it to our tracker of ideas for now. I’m sure other team members will be better at judging if and when this could be implemented. Maybe @MirceaGrigore can help here :slight_smile:

3 Likes

To try with other than the UiPath Orchestrator, May I know other services those who have the same url link as you you have with swagger.?

1 Like

I will update this guide whenever our team releases the API guidelines for the new authentication method :slight_smile:

EDIT

For anyone looking on how to authenticate, here’s a sample project:

Also, if you already have your new tokens, this is how you should run it from services:

The value of the dictionary looks like this:

new Dictionary(of string,string) from { {"Authorization","Bearer yourAccessToken"}, {"X-UIPATH-TenantName", "yourTenantName"}  }
1 Like

This is awsome :smiley:

2 Likes

This is great and we just finished doing a proof of concept to get this working but didn’t do it as Libraries. I think we will do that.
What i’m working on now is trying to find the end point that will give me the status of all the Robots. Can anyone help me out on this?
Thanks!

1 Like

Hi @tmartin

Would this one be the one you are looking for:

2 Likes

Thanks.

Tracy Martin

2 Likes

Hi @MaxT

The authentication was made more tricky recently, it is because of switch to cloud service. You can see this post here from slightly above:

It goes over how to get the access token that will basically replace the bearer token. It also states how to input this token in the service activities for them to work.

1 Like

Hi @Ioginerror
I want to trigger a UiPath Job with input parameters from another application through API call, I am trying to authenticate with new Cloud orchestrator, I tried with UiPath HTTP request, Postman and Swagger UI. But everywhere I am getting Invalid credentials error. How can I authenticate? How can I get the Robot ID and Release Key?

In Postman I have taken below End Point URL
https://platform.uipath.com/api/account/authenticate

In Swagger, I have taken URL like below
Orchestrator Account URL + /swagger/ui/index#/

{
“tenancyName”: “string”,
“usernameOrEmailAddress”: “string”,
“password”: “string”
}

I followed as mentioned in the https://forum.uipath.com/uploads/short-url/iZsjSYaXMTLLC10NKW2wkVVbUus.zip and executed the GetTokens.xaml, after logging to orchestrator portal, I am getting below error.

Error

Error%202

Looking for your help.

Thank you

1 Like

Hi @Ramprasad

Welcome back! :slight_smile:

The Authenticate endpoint is not relevant any more. Please follow the full procedure and you will generate the access_token that you will use instead of a bearer_token.

1 Like

Which is the full procedure then? Is it the 2019.4 update in academy? Is it the one posted above? Is it somewhere else? This part has become really messy and could use a cleaning.

Regards

1 Like

I agree. Currently, the Academy course and the above blog are both completely accurate for the on-premise installations of Orchestrator.

It is the free Cloud Platform Orchestrator service available at platform.uipath.com that requires some small changes to the process, due to the new, more secure authentication that was introduced with it.

5 Likes

Hi
I am going through the UiPath 2019.4 Updates Course . in the SOAP and Swagger Libraries section, when I am trying to create a new service, as per the video, by specifying this url “https://platform.uipath.com:443/swagger/docs/V2” in the File and Link textbox, I am getting "The document is invalid" error. I am using Uipath 2019.8.0 Community Edition
Please help

1 Like

Hi @AbhayGodbole

Please log in to your Orchestrator instance on Cloud Platform and look at the address. As per my post above yours, you will need to modify some things, including the address. This is the template:
https://platform.uipath.com/<cloudPlatfromName>/<orchestratorInstanceName>:443/swagger/docs/V2

More about here:
https://docs.uipath.com/orchestrator/v2019/reference#about-odata-and-references

And my post here, on how to run the Orchestrator calls via services feature:

1 Like