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 3^rd^ 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.
-
Create Case
-
Look Up Case
-
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 3^rd^ 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.
