Naming Conventions for Digital Interfaces & Digital Integrations in EA Workspace, Xanadu

[markterringon]

Hello & Happy New Year

We have moved to Xanadu and currently documenting all APIs & Integrations across our landscape.

I wanted to ask if anyone has a ServiceNow naming convention for the naming of Digital Interfaces?

I have seen suggested naming conventions for the Digital Integration, e.g., SAP_to_Salesforce_API_Prod_v1.0, but nothing for the Digital Interfaces.  I wanted to see if there was a common view or approach on this ?

Also, do you add the actual API URL in the description as a way to link the record to the actual API used?

Thanks for your help in advance.

Kind regards,

Mark

[Bruno De Graeve · Accepted solution]

hi Mark T, we do have a current limitation that the Digital Interface name field has been set to 40char. We already encountered that issue and have a story in our backlog to extend it to 120char. 

The Digital Integration name field is already set to 250 as some of the forms will auto-calculate a name for you.

regards, Bruno

[mcastoe · Accepted solution]

Many thanks Bruno!  the additional chars will make a naming convention much more viable.

@markterringon, as for the subscriber Interfaces, they are purely optional.  Some customer see need to model the "api on the other end" if it exists but that is not at all required.   Most i've seen do not use them unless if very clear the subscriber "interface" exists and required soem form of management.  Its sort of a value statement; does thsi record provide me value ? Does it enhance the visibility of how things work?   For me, it better to start simple and get value then enhance the model in use if there is call for it.

thanks,

mark c

[mcastoe]

Hi Mark,

great question and I'm very interested in what others have to say.  I've usually advised something like a "PROVIDER_APP_NAME"_"API_SHORT_NAME" for interfaces and "PROVIDER_APP_NAME"_"API_SHORT_NAME"_"SUBSCRIBER_APP_NAME" for integrations.  Something logical and short as possible which is a always a challenge in these things.   Some customers will use the App Numbers or an App Code in place of the name to help reduce space.

As for the URL, you could add the URL to the description but better is to define your "instances" as a cmdb_ci_api and set the URL there.  It maintains the differentiation of Design vs Deployment and if an Interface has multiple instances, you readily have the one to many structure.

thanks,

mark c

[markterringon]

Hi Mark,

Thanks for your reply.

I think we may go the other way in terms of naming convention, as it makes sense to have the subscriber first, then the type of action on the API, with the provider.  But since there is a 40 character limit on some of the "name" fields, this may also change.  For example, in an ERP a customer record may have many address locations, and those locations may have different contact persons.  So if you update a contact person from a location of a customer (which is different to a general contact), you may have a CustAddressContact which you are enacting CRUD (Create_, Update_, Delete_, etc.) functionality onto - so it starts getting quite long.

I am also having issues with the "subscriber interfaces", as these also have fields to populate (protocols, message format, authentication type, etc.).  All of which will be the same as the API provided by the Provider application.  Why would you have these?

It seems as if there is yet sufficient documentation to be able to add our APIs to ServiceNow.  There are no (proper) examples.  I understand the split between design and implementation, but having a subscriber interface still baffles me as to the applicability and usefulness - a business application has a number of APIs and other systems subscribe/use those APIs.  Why is there a subscriber record of the same API that has the same information?  You can't change the protocol details or message format as it is the Provider that dictates these.

So when we try and add the Interface records for the Provider APIs and then add Subscriber records matching them, and then link them both in the Integration record we get the entire list of Subscriber interfaces listed in the "Portfolio Health" as without Integrations.  But you need the Subscriber Interface records, to enable them to be listed in the dropdown list of the Integration Record.   

So I am clearly doing something wrong, but without documentation it is a blackhole of understanding.

Thanks and have a good week.

Mark T

[Bruno De Graeve · Accepted solution]

hi Mark T, we do have a current limitation that the Digital Interface name field has been set to 40char. We already encountered that issue and have a story in our backlog to extend it to 120char. 

The Digital Integration name field is already set to 250 as some of the forms will auto-calculate a name for you.

regards, Bruno

[mcastoe · Accepted solution]

Many thanks Bruno!  the additional chars will make a naming convention much more viable.

@markterringon, as for the subscriber Interfaces, they are purely optional.  Some customer see need to model the "api on the other end" if it exists but that is not at all required.   Most i've seen do not use them unless if very clear the subscriber "interface" exists and required soem form of management.  Its sort of a value statement; does thsi record provide me value ? Does it enhance the visibility of how things work?   For me, it better to start simple and get value then enhance the model in use if there is call for it.

thanks,

mark c