Workflow Automation CoE > Flows > Best Practices > IntegrationHub General

IntegrationHub Best Practices

Spokes

What is a spoke: A spoke is simply a ServiceNow scoped application for the purpose of a single integration.

• The Spoke should be responsible for doing an individual integration. For Example - Box Spoke should be responsible for doing a native integration with Box in terms of managing files and folders.
  
  • Spokes should only integration actions for a single 3rd party integration.
    
  • Your ServiceNow application may be purpose built with many integrations and ServiceNow objects for your outcome. This is ok, we just wouldn't call it a spoke, rather it's a ServiceNow application that includes some integrations.
    
  • Our best practice is to put each integration in its own app scope (aka a Spoke), for reuse across many other ServiceNow applications.
• Every Spoke requires a default Connection and Credential alias.
• Actions should have a category unless there are only a few actions in the entire spoke.
• By default, set scope access to "Accessible from all scopes" in actions. The scope should only be reduced if a spoke is proprietary to a given application. E.g. Benchmarks may have a spoke that is only ever used by the Benchmark app.
• The best practice is to only have a single integration call in an action, if possible. Do not include more than a single integration call in an action. An action should only have a single integration step.

Connection Alias

• Alias should be created in the scope of the Spoke.
• The name of the alias should match the name of the Spoke.
• The Spokes which use OAuth setup should include a default Application Registry.
• Application Registry name should match the spoke name.
• Alias should also ship the Connection Attribute for API version and this connection attribute can be used in the REST step as part of resource path for ex: /api/{version}/docs/
  
  • First define the API version at the connection attribute level.

Guidelines creating Introspection Actions

While using dynamic inputs (Dynamic Choice, Dynamic Templates etc..), follow the below guidelines:

• Try and normalize the 3rd^ party API consistently for CRUD (Create, Read, Update, Delete) operations using the following convention.
  
  • Create Record
    
  • Update Record
    
  • Look Up Record -- Ensures you can act on one object
• Consider surfacing the class record e.g. a third-party system has a Case Object. You may want to surface actions for that e.g.

Preprocessing

• If necessary, add a pre-processing step to perform input validation, such as checking for empty values in run-time. If input failures occur, create error handlers to enable the flow author a graceful message about the input failure.
• Use gs.error to log detailed error in case of failures.
• Add action error conditions for errors generated from Integration step like REST, PowerShell or SOAP.
• Use pre-processing to remove null inputs from request body, when necessary. There are few 3rd^ party systems that do not execute properly with blank inputs/values.

REST Steps

• Use Binary type and Multipart type of REST step to transfer attachments to integration system.
• Use the Version variable declared in Connection Attributes.

PowerShell Steps

• Utilize MID server script file to write PowerShell script.
• Use "$computer" variable to get the Target Server (For ex: - This variable stores the IP/FQDN qualified Domain name address of the server. Ex: In case of AD it will be the IP Address of the Domain Controller).
• Maintain only one function per ps1 file to maintain modularity.
• Write all utility functions in one psm1 file and re use them in ps1 files.
• Write necessary debug information to the logs in case of general error cases for debugging purpose.

Center of Excellence Navigation