How to Integrate External Systems with the Cireson Portal for SCSM

Integrate External Systems

The Cireson Portal comes with a variety of REST API’s that are available for consumption from within the Portal and externally from other systems.  This means that we can pretty much retrieve any data we want from Service Manager no matter where we are.  It also means that we can update and create things as well.  The API Documentation is located under the user menu in your portal.  You need to be logged in as an Administrator to see this menu item.  We will use sections of this in our demo below.

For this demo of how to integrate external systems we will use Postman which is a tool that is widely used to test API calls.  It comes in handy when developing against the API’s for the Cireson Portal.  It can be downloaded here:

https://www.getpostman.com/apps

GetToken API

The very first thing you need when interacting with the Portal APIs externally is a Token.  This is what authenticates you as a user and allows access to the data in Service Manager.  The account used here requires the appropriate permissions in Service Manager.  We won’t get into User Roles here, but my advice is to create a service account for these purposes and throw it in the Advanced Operators User Role.  The documentation for the GetToken API shows that you need to send the following parameters: UserName, Password, LanguageCode

1. Once you launch Postman, go to New à Request from the top right.
   
2. Give the Request a Display Name and place it in a collection.
   
3. You will be taken to a tab where we will configure our call. The documentation shows that we need to perform a POST to a URL in the Portal.
   
   So, within Postman we will change the method to POST and add the URL (to include the external web address).
   
4. Next, we will change the type to raw, select JSON(application/json), and then add the body which includes the parameters we are sending. It is important to include (2) backslashes between the Domain and Username.
   
5. We should be ready to go. Let’s go ahead and click the Send button.
   
6. You should get back a crazy looking response at the bottom of the page that looks something like the below. We will be using this response in the next section.
   

Create Projection By Criteria

Now that we have our Token we can interact with Service Manager via different API calls.  In this demo we want to create a basic ticket.  The API you need here is the CreateProjectionByCriteria call which takes in two parameters: id and createdById.

1. The first thing we need to determine is the template that needs to be used when creating this new ticket. Let’s keep it super basic and use the “Default Service Request” Template.  With a bit of PowerShell magic, we can get the Id.
   
2. We will follow the same steps from the previous section and create a new request based on the information we have from the API documentation. In this example we are going to send the parameters directly in the URL that is being sent.  Because this is a GET request, we don’t have the option to place this in the Body like we did above.  As you can see, we have added parameters at the end of the call (which looks very similar to the API documentation above).  It is also worth noting that we added createdById as a parameter but aren’t sending anything through.  The documentation shows that it is required so we must have it in the call.  We aren’t setting a value because we already are authenticated as the service account from the section above.
   
3. Next, we will add the Authorization Header. This is where the results from the previous GetToken API call come in handy.  You need to copy the response (minus the quotes around it) from the previous call.
   Then create an Authorization key with a value that starts with the word Token, a space, and then the pasted token key.  The space after Token is extremely important!!!!
   
4. Let’s go ahead and click send. You should now get a JSON result that looks like what you see below:
   

Commit API

So, what was that response we just got?  If you scroll through it you can see that is has an ID, a Title, a Class Name, and other information that you are familiar with as it relates to a Service Request Ticket.  This is essentially a blank Service Request that has an ID (auto-generated from your SCSM environment) and then whatever else is set in the template you are using.  It is important to note that the ticket has not been created yet.  Enter the Commit API.

The Commit API requires two parameters.  The first is the original work item and then the second is the same work item but with the changes you want.

1. Let’s create a new POST request and set the URL per below.
   
2. Next, we will set our Authorization Key and Value just like we did in the previous section.
   
3. Now the fun part. If you look at the API documentation, you can see that the body parameters need to be sent as follows:
   
   The Original Projection (work item) will be what we received back from the CreateProjectionByCriteria API.  The Current Projection is a copy of the Original Projection + any changes or updates.  Under the Body tab, select raw and then JSON(application/json).
   
4. Next, copy the below into the body section.
   {“formJson”: {“current”:datahere

   ,

   “original”:

   datahere

   }

   }

   

5. Go back to the Projection results you got from the previous section, copy it, and then paste it over each line that says “datahere”. As you will see, there is a lot of information here.  You can collapse this by going to the very top of the body section and clicking the arrow next to the underneath the current section and then underneath the original section. You will know you didn’t do this correctly if you see any red x’s next to your line numbers.
   
   
6. Just to prove that we can update data beyond what is in the template, let’s change the Title. Expand the “current” section and scroll down to locate the Title.  Change the value to whatever you like.
   
7. Cross your fingers and click Send. You should see something like this in the response:
   
8. Now the ultimate validation. Log into your portal and look for your new ticket and start doing backflips!!!!
   

If you made it this far, congratulations!  That was some serious stuff.  What did we learn here?  We can use an external tool (or system or application) to make API calls and interact with Service Manager.  Not only can we pull data, we can also create and update data.  We could get an active ticket via an API call, change the Support Group or Status or whatever else, and then Commit.  This process is a little cumbersome, especially when we got into the commit API and what is required in the body.  The key thing here is that we have a working example.  This can now be implemented in a more programmatic way that will take in these responses from the API as variables and then manipulate them as needed.

Let us know if this is of help and feel free to reach out through the Cireson Community for more tips and tricks!