Allow a User Web Portal to Automatically Sign a User into SBM

Recently, SBM has been used in conjunction with portal websites.  Once a user is logged into a custom web portal, it may be undesirable for the user to be required to also be forced to enter their password to login to SBM.  Why not just use the successful authentication to the portal site to authenticate the user to SBM?  This is now possible as of SBM 11.3.1 with the use of Single Sign On.

Continue reading
1483 Hits

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:


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
4135 Hits

SBM Composer: REST Service Calls Using the RESTServiceWrapper Object

Many SBM Composer users are familiar with the REST Grid, a widget that permits you to return iterating results from a REST service on a custom form. For more information about this feature, take a look at the SBM documentation and these blog posts:

Advanced REST Grid Configuration on Custom Forms
SBM 11.0: Using Custom Endpoints in the REST Grid Widget
SBM Composer 11.0: Modifying REST Data Before it is Rendered

But while this is useful for displaying tabular information from a REST service, what if that's not what you want? As is often the case, things that you can't do directly with the form editor in Composer can be achieved by writing a little bit of JavaScript and leveraging the SBM JavaScript Library.

Recent Comments
Brian Amos
If you try the example above make sure you use the HTML/Javascript widget on the form instead of an external .js file. The externa... Read More
Friday, 29 April 2016 10:10 PM
Tom Clement
Hi Brian, Thanks for the clarification on that point. I can see how you'd expect those variables to be evaluated inside of a .js... Read More
Friday, 29 April 2016 11:11 PM
Ashish Kumar
Thank you.
Wednesday, 19 July 2017 10:10 AM
Continue reading
8546 Hits

SBM Composer 11.0: Using Custom Endpoints in the REST Grid Widget

In this article, we'll drill down into the use of Custom Endpoints for REST Grids. As discussed in another blog post, custom endpoints are process app endpoints defined explicitly in Composer as opposed to endpoints created automatically for an imported WSDL or by a REST Grid widget configured with an URL.

Continue reading
7068 Hits

CM 14.2 New feature: RESTful web service API tutorial

CM 14.2 New feature: RESTful web service API tutorial

The REST API is a newly available API published in Dimensions 14.2. It presents a simple and light weight method of querying a Dimensions CM repository. By use of the HTTP Get method and returns results in JSON format.

In this PDF tutorial several methods will be used to demonstrate as to how these resources can be accessed.

Recent Comments
pandu sai
Helpful article.
Friday, 09 February 2018 8:08 AM
Paul Caruana
You are welcome Pandu.
Friday, 09 February 2018 8:08 AM
Continue reading
10432 Hits

Advanced REST Grid Configuration on Custom Forms

In SBM 10.1.5, we've added a powerful and flexible new way to configure the REST Grid widget.

The Problem

In earlier releases, to configure the REST Grid widget you would enter an URL to the REST service.  Composer called that service, obtained a result and used it to determine the expected structure of the REST data so it could be used for mapping to other controls.  However, this process failed in a number of circumstances.  For example, the Composer user might not have permission to access the REST service, or the service might not always return all the data elements that might occur in production use.

Continue reading
6364 Hits

Extending the REST widget to drive integration/workflow logic

The SBM REST widget provides an easy way to display information that is available RESTfully via 3rd party tools.  The REST grid is useful for displaying data and allowing selected rows within the grid to populate other mapped fields on the form, but out-of-the-box it does not provide an easy way to drive business/process logic.

Recent comment in this post
martin nicolas candal
Hi, I tryed to import the process app that you attached and I got this error message:Failed to import process app because of the ... Read More
Thursday, 02 July 2015 2:02 PM
Continue reading
7381 Hits
1 Comment

Recent Tweets