SmartCOMM DocGen (Preview)
Smart Communications is a leading technology company focused on helping businesses engage in more meaningful customer conversations.
The SmartCOMM On-Demand Doc-Gen Connector includes a pre-built integration for producing omnichannel customer communications. The connector provides RESTful webservice calls to SmartCOMM for on-demand use cases.
This connector is available in the following products and regions:
| Service | Class | Regions |
|---|---|---|
| Logic Apps | Standard | All Logic Apps regions except the following: - Azure Government regions - Azure China regions - US Department of Defense (DoD) |
| Power Automate | Premium | All Power Automate regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD) |
| Power Apps | Premium | All Power Apps regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD) |
| Contact | |
|---|---|
| Name | Smart Communications Support |
| URL | http://support.smartcommunications.com |
| support@smartcommunications.com |
| Connector Metadata | |
|---|---|
| Publisher | Smart Communications |
| Website | https://www.smartcommunications.com |
| Privacy policy | https://www.smartcommunications.com/external-privacy-policy |
| Categories | Communication;Content and Files |
Smart Communications™ is a leading cloud-based platform for enterprise customer communications. As the only cloud solution ranked as a Leader in Gartner’s Magic Quadrant for Customer Communications Management, more than 350 global brands – many in the world’s most highly regulated industries – rely on Smart Communications to make multi-channel customer communications more meaningful, while also helping them simplify their processes and operate more efficiently.
The SmartCOMM On Demand Connector for Power Apps includes a pre-built integration for producing Customer Communications. The connector provides RESTful webservice calls to SmartCOMM for on-demand use cases.
The connector support the SmartCOMM 'GenerateDocument' operation which generates a response including the base64 encoded byte[] output. Output supports different types of channel output. (e.g. SMS, PRINT, TEXT, XML, TML, XSLFO, HTML)
Prerequisites
In order to use the SmartCOMM component in Power Apps, you will need a few things completed first:
- A Microsoft Power Apps or Power Automate plan with custom connector feature
- A SmartCOMM instance set up for your organization with user access
- You will need to work with your Smart Communications contact to set up a document template to generate documents from.
- To configure your component settings - you will need to know the ‘BatchConfigResID’ or SmartCOMM Template Selector resource ID. Ask your Smart Communications contact to help you find this.
- Setup your SmartCOMM instance with an OAuth 2.0 Client (Authorization Code grant type)
How to get credentials
- Contact your SmartCOMM User Admin to create your user access
- Once your user access created, you will receive an email to activate your account
- Follow the instructions to activate your account
- In the Authorization Code flow, the SmartCOMM user that owns the resources in the SmartCOMM cloud authorizes clients to access their user account. Users will access the redirect URL to login the tenancy. Users can enter the their user name and credentials to access the tenancy for the first attempt. (the following attempts will pop up the access code page directly)
- Accept the request to retrieve the access code, by click the Accept button
- Clients then use access tokens to access the resources, not the user's credentials.
Get started with your connector
- Provide the host URL of the SmartCOMM instance
- Provide the OAuth 2.0 Client details - Client ID, Client Secret, Authorization URL and Token URL
- Provide the Power Apps generated Redirect URL (e.g. https://global.consent.azure-apim.net/redirect)
- Create a Data Connection to the SmartCOMM instance using a registered user account
- We need a complete document generator setup at SmartCOMM, which contains at least a template selector, a template and a data model.
- Create Connector
- required parameters:
- Region
- RegionServer for exmaple: eu10-sb
- Client Id
- It is the same as in the Provide the OAuth 2.0 Client details
- Client Secret
- It is the same as in the Provide the OAuth 2.0 Client details
- Region
- required parameters:
- Supply Request URL to generateDocument endpoint. E.g. https://.smartcommunications.cloud/one/oauth2/api/v10/job/generateDocument
- required parameters:
- Include Document Data
- yes as usual
- transactionData (Json or XML)
- no need for base64 encoding, because it is done by the connector
- it should be the same format as in SmartComm
- batchConfigResId
- Resource ID of the Smartcomm Template Selector
- projectId
- default empty, but have to be filled in when the SmartComm project is not released
- transactionRange
- it can be empty, but when filled in it should show what indexes should be used from the array
- transactionDataType
- application/json or application/xml
- it is the format of the transactionData parameter
- extra params like merge.pdf can be read on SmartComm API description
- https://.smartcommunications.cloud/one/apiViewer/
- Where is the Smart Communications server you're using (NA1.smartcommunications.cloud, EU1.smartcommunications.cloud, and so on).
- Include Document Data
- required parameters:
- SmartCOMM On Demand Generation connector generates the communication(s) and returns the response (including the base64 encoded output) to the Power App
- Returns an envelope array, which contains the base64 encoded documents.
- The document usualy inside of string
- The communication(s) can then be displayed in the Power App for download, archived (e.g. SharePoint, S3 bucket) or pushed to an output delivery service e.g. SNS, Outlook, mailhouse etc.
Known issues and limitations
- Rate limiting (check with your SmartCOMM Admin for more details as this is part of the Licence Agreement)
- Individual maximum request size is 10MB
Common errors and remedies
- Ensure 'transactionDataType' set to 'application/json' when using JSON payload.
- Ensure specify 'projectId' when you want to limit the scope within a SmartCOMM project
- Ensure 'includeDocumentData' set to true when you need th output to be included in the response
- Refer to Common error codes section below.
Common error codes
HTTP 403 - Generate Document has failed This error returns 'id' (the SmartCOMM error code) and the error 'msg' (the SmartCOMM error description)
HTTP 500 - Internal Server Error We also recommend that in the event of an error when you call the service, you wait five seconds before retrying. On multiple continuous failures, your service should alert users and stop submitting that call, as your request may be invalid.
HTTP 429 - Too Many Requests If you get an HTTP 429 response, you should wait 60 seconds, then retry your request.
HTTP 503 - Service Unavailable An HTTP 503 response is sent during maintenance. You should wait 120 seconds then retry your request. Maintenance windows could last an hour or more during a milestone upgrade.
FAQ
'Provide a breakdown of frequently asked questions and their respective answers here. This can cover FAQs about interacting with the underlying service or about the connector itself.'
Where Can I find further information about the 'GenerateDocument' service? - can be found here - https://.smartcommunications.cloud/one/apiViewer/#!api=doc-gen&operation=generateDocumentNonMultiPart&resource=Job
Is data encrypted using this connector? - Yes, if HTTPS is configured the connection will be encrypted end to end.
How can I get a SmartCOMM user account? - Contact your SmartCOMM user Admin.
What's the authorization type? - OAuth 2.0
How can I get the OAuth2 Client ID and secret? - Contact your SmartCOMM admin or refer to https://.smartcommunications.cloud/one/help/oneplatform/en/index.htm#EditClient.htm
How can I get the authorization code? - Refer to section 'How to get credentials' above for full details.
How can I get support for this connector? - Contact support@smartcommunications.com for all support enquiries
Where can I find more information about the SmartCOMM product? - https://www.smartcommunications.com
How can I get the batchConfigResId? - Contact your SmartCOMM SME or refer to https://.smartcommunications.cloud/one/help/oneplatform/en/index.htm#ResourceProperties.htm.
How can I get the projectId? - Contact your SmartCOMM SME or refer to https://.smartcommunications.cloud/one/help/oneplatform/en/index.htm#ResourceProperties.htm.
How soon will I get the response? - The response time can vary based on your network speed, payload size and resource complexity, etc. SmartCOMM recommends to run a performance baseline to collect the maximum response time and average response time
How can I get the output from the response? - The successful response includes the base64 encoded byte[] output. To view the output, actions have to be taken to decode the byte[] output and save the copy in a format as specified in the "mimeType". For more details please refer to https://.smartcommunications.cloud/one/apiViewer/#!api=doc-gen&operation=generateDocumentNonMultiPart&resource=Job
Creating a connection
The connector supports the following authentication types:
| Default | Parameters for creating connection. | All regions | Not shareable |
Default
Applicable: All regions
Parameters for creating connection.
This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.
| Name | Type | Description | Required |
|---|---|---|---|
| Region | string | Enter Smart Communications region | True |
| Client Id | string | Enter OAuth Client Id | True |
| Client Secret | string | Enter OAuth Client Secret | True |
Throttling Limits
| Name | Calls | Renewal Period |
|---|---|---|
| API calls per connection | 100 | 60 seconds |
Actions
| Generate Document |
This function generates a document. |
Generate Document
This function generates a document.
Parameters
| Name | Key | Required | Type | Description |
|---|---|---|---|---|
|
Include Document Data
|
includeDocumentData | True | boolean |
Boolean flag to determine whether generated document data should be provided directly. Possible values are true or false. If true, base64 data will be provided for each channel result. If false, a URL for retrieving the data will be provided for each channel result. The document data returned in the response will be Base64 encoded. |
|
projectId
|
projectId | integer |
The CMS project ID used to scope the request execution. If this value is not specified then the job will execute in production mode. |
|
|
transactionData
|
transactionData | True | string |
The sample data. |
|
batchConfigResId
|
batchConfigResId | True | integer |
The CMS ID of the Template Selector resource. The Template Selector is used to map the transaction data to the Template and Data Model. |
|
transactionRange
|
transactionRange | integer |
transactionRange |
|
|
transactionDataType
|
transactionDataType | string |
The content type of the transaction data. Can be 'application/xml' or 'application/json'. Defaults to 'application/xml'. |
|
|
name
|
name | string |
The property name. |
|
|
value
|
value | string |
The property value. |
Returns
| Name | Path | Type | Description |
|---|---|---|---|
|
exceptions
|
exceptions | array of object |
exceptions |
|
classId
|
exceptions.classId | integer |
The code of the business exception. |
|
id
|
exceptions.id | integer |
The unique ID of the business exception. |
|
className
|
exceptions.className | string |
The description of the business exception. |
|
msg
|
exceptions.msg | string |
The user-defined exception message. |
|
previewKey
|
previewKey | string |
Key is used to retrieve document parts. Not used when includeDocumentData is set to true in the request. |
|
numberTransactions
|
numberTransactions | integer |
The number of transactions encountered in the job. |
|
dataModelValuesLocation
|
dataModelValuesLocation | string |
The reference to the data model values part. |
|
envelopes
|
envelopes | array of object |
envelopes |
|
startPage
|
envelopes.primaryChannel.startPage | integer |
The start page number of an enclosed document in the primary merged print document. |
|
pageCount
|
envelopes.primaryChannel.pageCount | integer |
The number of pages in the document generated. |
|
channelType
|
envelopes.primaryChannel.channelType | integer |
The type of the channel. Possible types are: '1' TYPE_HTML '2' TYPE_PRINT '3' TYPE_SMS '4' TYPE_TEXT '5' TYPE_TML '6' TYPE_XML '7' TYPE_WORDML '8' TYPE_XSLFO. |
|
channelName
|
envelopes.primaryChannel.channelName | string |
The name of the channel. |
|
properties
|
envelopes.primaryChannel.properties | array of object |
properties |
|
name
|
envelopes.primaryChannel.properties.name | string |
name |
|
value
|
envelopes.primaryChannel.properties.value | string |
value |
|
data
|
envelopes.primaryChannel.data | string |
The document data encoded as Base64. Only populated when includeDocumentData is set to true in the request. |
|
documentName
|
envelopes.primaryChannel.documentName | string |
The name of the document generated. |
|
mimeType
|
envelopes.primaryChannel.mimeType | string |
The content type of the document. |
|
channelId
|
envelopes.primaryChannel.channelId | integer |
The channel Id of the document. |
|
partLocation
|
envelopes.primaryChannel.partLocation | string |
The reference to the document part for retrieval via the cachedItems method. This is not used when includeDocumentData is set to true in the request. |
|
enclosureChannels
|
envelopes.enclosureChannels | array of object |
enclosureChannels |
|
startPage
|
envelopes.enclosureChannels.startPage | integer |
startPage |
|
pageCount
|
envelopes.enclosureChannels.pageCount | integer |
pageCount |
|
channelType
|
envelopes.enclosureChannels.channelType | integer |
channelType |
|
channelName
|
envelopes.enclosureChannels.channelName | string |
channelName |
|
properties
|
envelopes.enclosureChannels.properties | array of object |
properties |
|
name
|
envelopes.enclosureChannels.properties.name | string |
name |
|
value
|
envelopes.enclosureChannels.properties.value | string |
value |
|
data
|
envelopes.enclosureChannels.data | string |
data |
|
documentName
|
envelopes.enclosureChannels.documentName | string |
documentName |
|
mimeType
|
envelopes.enclosureChannels.mimeType | string |
mimeType |
|
channelId
|
envelopes.enclosureChannels.channelId | integer |
channelId |
|
partLocation
|
envelopes.enclosureChannels.partLocation | string |
partLocation |
|
jobMessages
|
jobMessages | array of object |
jobMessages |
|
args
|
jobMessages.args | array of string |
args |
|
msgID
|
jobMessages.msgID | integer |
The ID of this message. |
|
destID
|
jobMessages.destID | integer |
The ID of the destination. |
|
msgType
|
jobMessages.msgType | string |
The message type: info (I), warn (W), or error (E). |
|
msgText
|
jobMessages.msgText | string |
The message text. |
|
msgDate
|
jobMessages.msgDate | string |
The date/time of the message. |
|
transactionNo
|
jobMessages.transactionNo | integer |
The number of the transaction. |
|
packageID
|
jobMessages.packageID | integer |
The ID of the package. |
|
batchID
|
jobMessages.batchID | integer |
The ID of the batch. |
|
docID
|
jobMessages.docID | integer |
The ID of the document. |
|
channelID
|
jobMessages.channelID | integer |
The channel ID of the document. |