Best Practices ​

Definitions ​

Active Customer: A customer with one or more policies in force.

Customer: Client Type is set to Customer and the client file is not archived.

Policy in Force: Policy has an active status (Active, New, Renew, etc.)

Determining Client Status ​

First, client status is not automatically set by CMS. It must be set by the user. As a result, it is not 100% reliable in determining if a client should be considered active. This field holds a combination of business and sales pipeline statuses. Active and inactive statuses imply that a customer has an active policy or has no active policies. Prospect and Lead imply the client has at least one policy in the sales process. If the agent does not set this correctly, it’s possible to have an active client with no active policies and vice versa. To check if a client is active, the integrator must look at the status of each policy for that client, use their own business rules to determine the relevance of that client to them, and import data accordingly.

Some integrators may wish to put this responsibility on the agency users, requiring them to set a client status to active before they bring it into their system. Others may choose to go deeper, interpreting various layers of business rules and statuses in order to determine which client files are relevant to them, regardless of the status of the client file.

Determining Policy Status ​

To determine policy status, please refer to the policy status business rules supplement. This document contains information to determine the policy state (summarized below). This involves understanding policy status dates such as expiration, cancellation, and inception, and what they mean.

IMPORTANT: Since CMS is a file-based system, the data stored in the client file is static. It is possible for the file to contain dates that are in the future or from the past. When a vendor pulls a client file from the Partner API, it is important to know that the data contained in the client file is the data that was stored the last time the client file was saved in CMS… NOT as of the time it is retrieved from the API. If the integrator wishes to display the current policy status in their system, they must understand the business rules and calculate the current status each time the client file is read.

Two-way API Best Practices ​

From the original Pilot of our 2-way API release, HawkSoft heard the following feedback from pilot agencies.

• When writing a Log Note and/or Attachment back to a Client, it is always preferrable to an agent that the Log Note be associated with a Policy.

  • In HawkSoft workflows, a user rarely writes a Log Note generically to the Client. Their actions are almost always related to a Policy.

• URLs are not clickable inside a Log Note. They must be Copy-and-Paste’d out to a web browser. Additionally, URLs are not permanent or immutable. If they change or break, the documentation becomes incomplete. In all cases where it is possible, we recommend either:

  • Adding the entire contents of messages/emails/automated communication to the Log Note as plain text

  • Generating a PDF containing the contents of messages/emails/automated communications and attaching it to the Log Note.

• If documenting an email, Pilot Agencies expressed a preference for prominently placing the Subject of the email at the start of the Log Note. When possible, including that Subject as part of the Log Description was also preferred.

• Suspenses can be used to signal a HawkSoft user to review a Log Note or Attachment – it isn’t strictly necessary to have a Suspense relate to a follow-up action.

  • If there is something in the action being documented that a person should see, add a Suspense.

This list will be updated as HawkSoft gathers more feedback.