Skip to main content
Matrix42 Self-Service Help Center

Service Custom Form

Overview

Very often when shopping for a Service in Service Catalog, a lot of additional information needs to be obtained from the service Requestor. For that purpose the Service designer is able to define a special Custom Form (literally Configuration Item) which will be requested anytime the Service is added to the Shopping Cart, or Order directly. In advanced cases, some additional data for provisioning of the Service needs to be received not only from the Requestor, but also from those who approve the Order. For that purpose, the same Custom Form could be used.

Designing Custom Form

To declare and design the Custom Form the following steps need to be completed:

Define the Custom Form Data Model (Schema)

As for any other case in Service Management, you need to setup a new Configuration Item, which keeps all the data submitted on placing an order. In case a Configuration Item is created for the purpose of being used as a Custom Form, it has to include one of the predefined Data Definitions: either “Service Form Base” (SvcServiceFormBase) or Main Data Definition (SPSCommonClassBase).  From the System performance perspective, it is highly recommended to use a Simple CI based on the “Service Form Base” (SvcServiceFormBase).

Setup Custom Form for Service

To associate the created Configuration Form with the Service (simple or combined), set it in the Provisioning Tabulator of the Service Dialog for the "Service Portal Form" property.

ServiceProvisioning.png

Design appearance of Custom Form

From the System perspective, the Custom Form is an absolutely ordinary Configuration Item, which could be fully or partially managed in UUX.  To do that all the necessary UUX artifacts need to be defined for the CI, like Dialog, Preview, etc. But if the purpose is to have only a Form on ordering of the Service, it is enough, of course, to define only the Dialog. For that proceed to Layouts/Dialogs management area and create a new Dialog for the just created Configuration Item.

Use the Layout Designer to author the form

If the Dialog is going to be used as a Custom Form, you need to keep in mind that only the first Dialog View (Dialog tabulator) is displayed to Service Requestor, and exactly the first view needs to have all the controls needed to be provided by Requestor. Others tabulators can be used either for further Data management, or as additional forms requested to be filled by Decision Makers on approval.  

On designing the Custom Form, sometimes it is very important to get current Shopping context information, e.g. which Service is being added to Cart (especially for cases when the same Form is reused in multiple Services), who is the Order Requestor, or for whom the Service is shopped. All this information can be obtained in the Layout Designer Context section. Since not every Dialog is going to be used as a Custom Form, by default this data is hidden, but could be easily activated. Select the Context Data Source and Add new Property with name “ServiceDetails” of type Object and "ServiceForms" of type Object and checked IsArray flag.
 

clipboard_e066b253c1ca07dbe74552f69a2bbfd8a.png

 

The System automatically attached the Javascript object of the following structure to the declared Property:

ServiceDetails: {
    Catalog:  { Id, Name },
    Recipient,
    Id,
    Name,
    ItemNumber
},
ServiceForms: [
    {
        ServiceId,
        Data: {}
    }
]

ServiceDetails -  contains information about shopped Service
    Catalog – Object ID and the Name of the Service Catalog from which the Service is ordered;
    Recipient – Id of the Recipient of the shopped Service;
    Id – Id of the Service object;
    ItemNumber – Service's internal number;

ServiceForms: - an array of already filled on previous steps Custom Forms
    ServiceId – Id of the Service related to the form
    Data - the entity object created as a result of Custom Form filling

By using the "Add Property" function for the ServiceDetails and ServiceForms properties, you can fully re-create the Model of the Object, and then use the Object properties directly, or you can refer the ServiceDetails or ServiceForms properties in calculated fields, and use simple Javascript to get specific property value (like shown in Example below)

On the Image below, the example of the run-time data of the ServiceDetails and ServiceForms properties is presented:

clipboard_e20005df69f418c153a6eba25af9ef5fd.png

Example

The following example demonstrates how the ServiceDetails object could be used in defining the logic of the Custom Form. It initiates the value of a Property by the name of the ordering service

image.png

 

Design Custom Form for Decision Makers

For very intricate cases, the additional data could be requested from Decision Makers on Order approval. For that purpose, define additional View in Custom Form dialog (any View except the first, which always play a role of Custom Form for Requestor). Make sure that no Database Mandatory attribute is used on that View, otherwise the Requestor (which does not see this form) would not be able to submit the Custom Form. If you really need to ensure the Decision Maker provides the necessary data, use the appropriate Control validators, or special control like Form Message for validating the form.

To activate the designer Custom Control View to be displayed on approving, adopt the appropriate Approval Workflow to reference the concrete Dialog View from concrete Approval Step.

 

  • Was this article helpful?