Featured

How to test GSOAP webservice call

We have all had that issue with the Repository or the Orchestration Engine being unable to get to the gsoap web service URL.  And, this is with all SBM components installed on the same server.  Why can't it get to itself?  Or in the case orchestrations, maybe we cannot figure out why the OE is unable to reach a third party web service.

Continue reading
4655 Hits
0 Comments

Increasing Collaboration in SBM with Slack

In today’s technology stack, most teams have procured tools that enable collaboration such as HipChat, Slack, Microsoft Teams, and many others. These tools have become central to the efficiency of teams, enabling distributed teams and even local teams to constantly communicate and know what is going on.

In this blog post, we are going to explore how we can integrate an SBM Process App to post messages to a particular Slack channel when an item is submitted. These same principles could apply to any collaboration platform that provides the necessary APIs to communicate. This blog post will also describe some of the functions available to you in SBM such as Custom Events, text processing during Orchestrations using the Calculate step, and mapping fields in your primary workflow to the Event we created.

Note: Orchestrations can become a very complex topic. While this post aims to cover how to create this integration at a basic level, it does assume some understanding of how web services work as well as some more advanced SBM functionality. Serena does provide training classes to introduce the Orchestrations concept and should be taken if you have not worked with Orchestrations before.

First, why would we want to do this? Let’s think about an IT Service Desk. We might have 10 Level One technicians who are using Slack to communicate, asking for advice, and for general fun. They are using Serena Business Manager with our Serena Service Manager solution to manage their tasks and tickets. When a new ticket comes in, how are those technicians alerted to it? In the past, you and the other members of your team would receive an email notification from SBM. Now, with this integration, we will actually create a Slack Bot that will receive the message from SBM and post directly in to the Service Desk’s Slack channel that they are already using for collaboration.

First, let’s create this bot. After logging in to your Slack team, browse the Slack App Directory and you should search for “Incoming WebHooks”. This is a native Slack capability.

Click “Add Configuration”

You’ll be brought to a screen where you choose either an existing Channel that you would like to hook to or create a new one. For this example, I’ve got an existing channel called “servicedesk” that I want to hook in to.

 

Click “Add Incoming WebHooks integration”. This will create a dedicated Webhook URL that we will use in SBM to make REST calls to. The web page that displays will contain the dedicated URL as well as Configurations for the WebHook. One thing you might want to do is change the name of the bot that will be posting these items. You can do this by editing the name under the “Customize Name” section and saving the changes.

  

Keep this Window open for future reference.

Now let’s move to SBM…

We are going to use Orchestrations for this particular integration. Open the Process App that you want to put this integration in. In this case, I’m going to add it to our SSM Incident Management process app since I want to communicate with the Service Desk every time we have a new ticket.

We’re going to right click the Process App, choose “Add New”, and click Orchestration

`

You’ll provide a name for the Orchestration Application. I chose to call my Orchestration 'Slack'.

Right click on Orchestration Workflows and choose “Add New Workflow”

 

Rename the workflow from SlackWorkflow to something a bit more descriptive of what the workflow accomplishes, for example “SendIncidentSubmittedNotification”. After we’ve renamed the workflow, let’s establish what we need for our Working Data. To do this, click on the Data Mapping tab:

 

First, we’re going to right click Working Data and add a Complex Type value by clicking “Add New” and select “Complex Type”. Give it a descriptive name, such as “RequestXML”.

 

Now we need a child element of RequestXML called “TextDoc”. This element uses the specific name TextDoc to tell the RESTCaller to specifically denote that the value for this element is text and not XML or JSON. To add this, we’re going to select “RequestXML”, right click and navigate to “Add Child” and select “String”.

In the end, your structure should look like this:

The last step of setting up our Working Data is to remove the Namespace from the TextDoc parameter. This allows proper parsing of the element when it’s processed. This is documented in the Orchestration Users Guide. (http://help.serena.com/doc_center/sbm/ver11_2/composer/ttst_restcaller_arguments.html)

To make this change, we’re going right click on TextDoc and choose Properties. You will now have a side pane that displays similar to the one shown below.

Select the value in the Namespace property and remove it. This will allow the RESTCaller to parse the TextDoc properly.

To exit property mode, click on the blue diving line and it will restore the Property Editor back to Mapping mode.

Now that we have our Working Data setup, let’s create an Event that will trigger this orchestration. We’re going to define a custom event which will reduce the amount of unnecessary data coming to the Orchestration Engine. This custom event can be modified to allow you more data to use in your message as desired. For this example, we are going to create an Event that provides us with the Item ID and the Title fields.

To define an Event, we need to go to the Extensions section of SBM Composer. To do this, you’ll click on Extensions in the lower left portion of your screen.

Next, we’ll right click on Application Links under the Slack orchestration application. Click on “Add New Event Definition…”

I’m going to call this Event Definition “PostNewIncidentToSlack”. We’ll set the Product Name to be “Slack”. You can use the description of each field to determine what makes sense for your integration. Click OK when completed.

Now we are presented with the Event Definition Editor. This is where we will configure the data we require for the Orchestration as well as the different Object Types and Event Types. We will create an Object Type of “Incident” and an Event Type of “NewIncidentSubmitted”. Next, we’ll right click the Extension element and add two child String values: One called “ItemID” and the second called “Title”. The resulting editor should look similar to this:

Next, we’ll map this Event to kick off our newly created Orchestration workflow. To do this, we’re going to click on “Event Map” in the Property Editor.

We’ll click the “Add….” Button found on the right side of the screen and choose the “SendIncidentSubmittedNotification” workflow that we defined early. Click OK.

Now that we have exposed values to the Orchestration workflow, we need to export the Event Definition so we can use it in another application. To do this, go to the General Tab of the Property Editor and choose “Export event definition…”.

Save the file somewhere that you’ll be able to access it later in this tutorial. I saved mine to the Documents folder.

Now, let’s go ahead and finish the workflow. Click “Workflow Design” and select the “SendIncidentSubmittedNotification” workflow.

This is going to be a pretty simple workflow with only two steps. Our first step is going to be a Calculate step. To do this, click on Calculate from the Step Palette found on the right side of the screen and drag it in to the workflow between Start and End. You should now have a workflow that looks like this screenshot:

Let’s rename this step to be something a bit more descriptive, such as “CreateMessageString”. This is where we will create the string that will be passed to Slack. Now, start configuring the step by clicking on “Options” in the property editor.

For our Target expression, we’re going to specify where the Expression should be stored at the end of the step. We’re going to insert the value to “RequestXML\TextDoc”

Next, we’ll set up the expression we are going to use. We’ll use the CONCAT() function to piece together these values in a logical way and properly formatted for the structure Slack has defined.

The format that Slack has defined can be found on the same web page that provided the URL that we’ll be calling. In my case, the sample they provided me looks as follows:

payload={"text": "This is a line of text in a channel.\nAnd this is another line of text."}

So our challenge is to replicate that structure within SBM. I’ve copied and pasted the expression we will be using here:

CONCAT('{"text":','"A new incident has been submitted:\n', EventNotice\Extension\ItemID, ":", EventNotice\Extension\Title, '"}')

First, you might notice that the “payload=” section is missing. This is because there are two ways (as of this blog post) to interact with this URL: Either passing in the data in the body of your HTTP POST request or passing the value as a parameter. The example Slack provides demonstrates how to pass in the data as a URL parameter. We are using the primary method of passing the data in the body of the HTTP POST request. For this, all we need is the data (everything after the = sign).

Let’s break down this function a bit. The first piece we are putting in is:

‘{“text”:’

We are starting the String with a Single Quote because this is how we allow use of quotation marks in Orchestrations. If you need to embed Double Quotes in the resulting string, enclose the string with Single Quotes. If you need to embed Single Quotes in the resulting string, enclose the overall string with Double Quotes.

In this case, we need to format the message with double quotes embedded, so we begin with single quotes for this piece of the string.

The second piece of the string is ‘”A new incident has been submitted: \n’

This is simply a message that will be posted in the Slack channel. Because the format above calls for the value after the colon to start with a quote, again we begin this piece of the string with a Single Quote. The \n is used to denote a new line.

The third piece of the string is EventNotice\Extension\ItemID. This is where we are starting to pull data from the Event we received kicking off this Orchestration Workflow.

The rest of the pieces are very similar to the above pieces, with the last piece closing out our overall string with a Double Quote and a brace.

Now that we have our String created, let’s go ahead and set up our Web Service Call. To do this, we’ll pull over our RESTCaller Service from the Step Palette. We can rename this to something a bit more descriptive, such as “CreateMessageInSlack”. Since the Slack documentation specifies that we need to perform a POST operation, change the operation from “get” to “post”.

Next, we’ll click on Data Mapping and start configuring our POST web service call.

In the “restUrl” input, set the default value to the URL provided to you when you created the Slack Incoming WebHooks service.

Next, we’ll expand the options for the Web Service call and we’re going to set the Default Value for “sendAsText” to True. This will ensure that we send a text string instead of attempting to format the call as JSON or XML.

Finally, we’ll set our bodyXML input to the parent XML Working Data variable we created called “RequestXML”. To do this, we’ll click on the “Source elements” for the bodyXML input. Notice that Working Data does not have any available options to select. In order for us to get the RequestXML element, we have to check the “Permit incompatible types to be mapped” option. The reason for this is because we have defined a ComplexType but the “bodyXML” parameter is looking for a specific type called “anyXML”.

After I’ve done that, I can now select the “RequestXML” variable and click the OK button.

With that, we have finished configuring our Orchestration Workflow. Our final step is to choose where in the Incident creation process we will call this orchestration. These steps will vary for you depending on the application you are integrating. I am going to use our Serena Service Manager Incident Management process app.

For the Incident Management workflow, I have two points that I want a Slack message generated: When an end user uses the Web Interface to submit an item or when an email arrives through the Email Submit transition. To accomplish the first requirement, I’m going to choose to put the Action on the Otherwise step from the decision tree since I do not want a notification if the ticket is automatically going to be closed.

After I’ve clicked on the transition, I’m now going to go in to its Actions by click on the Actions button in the Property Editor. Click on “New…” which will launch the Action Wizard:

By default, the Action Wizard selected “Orchestration Workflow” which is appropriate for this use case. Next, we’re going to change the rule description by clicking on “the local event”. Since we defined a custom event, we need to perform the appropriate mapping. Clicking on “the local event” will trigger a change to “an external event”.

Click the Next > button. We want to affect this item, so we’ll go ahead and click Next > again. We don’t need to check a Condition so we will leave this as “Unconditionally” (Side note: If you wanted to only create Slack Events for Priority 1 tickets, you could use the Field Value condition to define that logic.). Now we will select the “External Event” we want to raise. Clicking the dropdown, the Incident Management application does not have any external events defined so we will chose “+ (Add new external event...)”.

Clicking that might prompt you to check out elements of the application you may not have checked out such as the “Type Library”. Once the checkout has occurred, you will be presented with an “External Event Configuration” dialog.

To begin, click the … button. Select the External Event Definition file that we exported earlier in this tutorial. You’ll see that we have fields populated in the dialog. Click OK to this dialog box.

You’ll notice that we now have some additional options in our Action Wizard. We can choose what Object Type and what Event Type this action should call. In our case, we have only defined one Object and one Event, so all that is left is to create the data mapping. To do this, click on the “data mapping” hyper link in the rule description area.

That will bring up a Service Mappings dialog box that allows us to map the fields in the application to what fields the Event has defined.

To map the data, click on the Application data cell for the field you wish to map. That will display a list of available SBM fields to map data to. You can also define a Constant value in the third column if necessary. For this integration, we will only be mapping data with no constants defined.

Now that I’ve mapped my data, click OK. Now click Finish on the Action Wizard dialog. That will save the Action to the transition. Now that we’ve done one of our transitions, let’s repeat these steps with the second transition, “Email Submit”. The procedure is the same with the exception that we will no longer need to import the External Event Definition. We’ve already imported it once so now it can be re-used throughout the rest of our application.

After you’ve done the data mapping, go ahead and click Finish. Once this is complete, let’s deploy our application. After deployment, go ahead and create a new item in SBM and go check the Slack channel.

 

Congratulations! You were successful! To recap, here’s what we did:

-Created an Incoming WebHooks integration (Slack)
-Added an Orchestration application to an existing SBM application
-Configured the Orchestration with a Custom Event Definition, allowing us to efficiently pass only the required data to the orchestration.
-Configured the Orchestration Workflow to create the necessary string and the Web Service call using the RESTCaller service native to SBM.
-Triggered the Orchestration at two points in an SBM workflow.

I hope you found this educational and provided a real-world example of how you can use the Orchestration Engine to enable collaboration using existing platforms in your environment.

Continue reading
4133 Hits
0 Comments
Featured

How to automate deploy/promote operations in Application Repository.

SBM Application Repository exposes web services which can imported into Composer to perform repository operations. These SOAP web services can be used in orchestrations to automate deployment and promotion operations. I would like to present a small process application with orchestrations which provides a way to retrieve all process application and snapshots from an SBM Application Repository instance.

Recent comment in this post
Andreas Theisges
Thanks for this. Is there a possibility to call a promotion profile using a web service?
Friday, 30 September 2016 12:12 PM
Continue reading
7869 Hits
1 Comment

SBM Orchestrations Calling RESTful Services

Back in SBM 10.1.3, we included a new feature to call REST web services with orchestrations.  The RESTCaller is included in the Composer interface after you upgrade.  You simply drag it onto your orchestration flow diagram and start to configure it the same way you do SOAP based web service calls.  Since this is essentially a wrapper, there is a little bit of translation that you will have to do.  There are two resources that you will want to reference. 

Recent comment in this post
Tom Clement
Great summary Erika.
Saturday, 16 May 2015 5:05 AM
Continue reading
8638 Hits
1 Comment

Integrating SBM / Release Control with ServiceNow

This is my experience with integrating SBM / Release Control with ServiceNow at a recent customer engagement.

Requirements: The customer had a variety of systems in place, and one dept was using ServiceNow. The requirement was to create a Change Request ticket in ServiceNow, upon the completion of a Release Package in Release Control.  This use case was mostly for record keeping, as the Change Request in SNOW was created, populated with data from SBM, and then set to be completed.

Recent Comments
Rose Wellman
Thanks for the write up
Friday, 22 May 2015 1:01 AM
Vickie Ortega
Nice write up! This gives me a couple ideas for a customer I'm working with too.
Friday, 23 September 2016 7:07 PM
Continue reading
9422 Hits
2 Comments

Recent Tweets