AIM Web Service Functions and Tags

In this topic, we continue our discussion of the commands located on the Edit Menu.

Web services are self-contained business functions that operate over the Internet. They are written to strict specifications to work together with other similar kinds of components. Web services are important to business because they enable systems in different companies to interact with each other, more easily than ever before. AIM Web Service is a tool that provides you with access to your AIM (Agency Information Manager) database in a secure and structured manner enabling you to interact with the data in real-time. Using Web service, you can create custom applications for a broad range of services. A typical application would be a Web based application that could create a submission, quote, and/or invoice in AIM without having to re-enter the data.

Scope

Web Service is provided to enable you to utilize your investment in your AIM database. It is not an out-of-the-box application that provides any direct functionality. You will need to create the user interface application that accesses the web service via XML.

The AIM Web Service allows a Web service client to connect to and interact with the AIM database via XML and stored procedures.

The table below highlights various tasks and the associated ownership of each:

Vertafore Provides

You Provide

WCF Web Services

Web site, Web developer, or server administrator

XML data interface to specific areas of the AIM database

Web site hosted on an accessible server

Technical documentation describing the data interface and its usage

Web page design or Java script programming. Web Service does not provide any data validation

User validation via a logon function

Integrated Web page usage into AIM user workflow

Configuration program

Loading or configuring of your Web server

Test client and source code

Access control provided through your Web site utilizing our logon function

Input/Output Functions

The following tables show the standard input and output function formats.

For standard input functions:

Input XML format

<CISWebService>

<procedure name>

<parameter1>value</parameter1>

<parameter2>value</parameter2>

</procedure name>

</CISWebService>

Where:

Procedure name =

Parameter (x) =

Value =

The name of the function being called

The name of the input parameters

The value for that parameter

Example

<CISWebService>

<WSInsuredSearch>

<SearchValue>osb</SearchValue>

<AgentID>AGT1109</AgentID>

</WSInsuredSearch>

</CISWebService>

For standard output functions:

Output XML format

<wsresults>

< recordtype name field1="value" field2="value" … />

</wsresults>

Where:

Recordtype =

Field (x) =

Value =

The type of record returned (generally table name), i.e., -Insured

Logon

The name of the table field

The field value.

ACORD XML Imports and Exports

Imports ACORD XML data. This includes named insured, submission data, version data, and units at risk information.

In AIM 6.5 the only units at risks data imported is general liability.

In AIM 6.5.1 the units at risk data imported is the above along with commercial property, crime, commercial inland marine, commercial package (general liability, commercial property, crime, and commercial inland marine), homeowner, and dwelling fire.

 

wsAcordXmlImport(pInputXML: String, tokenString: String): String

Input parameters

pInputXML – is the text of the ACORD XML

tokenString – is the authentication token returned by the WSLogin method

Details

  1. If the ACORD XML has the quoteID and insurerID the information can also be updated.

    If the version for that quoteID, specified in the ACORD XML, already has been quoted then a new version is created.

    Note: All information is updated. This includes named insured, submission data, version data, and units at risk information.

    Business Rule Validation

    The InsuredName must be provided for successful import.
  2. The effective dates and expiration dates must be valid for successful import. For example, the expiration date cannot be before the effective date.
  3. The ProducerID (agent) must be provided for successful import.
  4. The CoverageCode must be valid and mapped in Data Maintenance Utility (DMU) for successful import.
  5. The number of characters must respect the established field lengths. The InsuredName field is set to 255 characters; therefore characters over 255 will cause a schema validation error.
  6. If a product code is provided, it must correspond to a valid product for the given coverage.
  7. The agent must not only be provided, but it must also match a valid agent ID in the CIS database.
Schema Validation
  1. Format of dates must be exactly YYYY-MM-DD for successful import. YYYY/MM/DD (using slashes instead of dashes) is an example of an invalid date format and a schema validation error will be displayed.
  2. The order of nodes must follow ACORD standards for successful Import. Refer to the ACORD Help file for more information.
  3. A schema field length is set on most text fields and should be respected. For example, the InsuredName field is set to 255 characters; therefore any additional characters will cause a schema validation error.
  4. Numeric values cannot contain non-numeric data. For example <Amt>$500.00</Amt> will return a schema validation error and should be changed to <Amt>500.00</Amt>.
  5. All nodes marked as ‘Required’ in the ACORD Help file must be present in the XML. If a required node is missing or is in the wrong place a schema validation error will be displayed.
  6. Certain nodes have restrictions where their values must come from a pre-defined list. Refer to the ACORD Help file for the list. For example, the LOBCd node value of CGL is in the pre-defined list, but CXL is not and would cause a schema validation error.

Output fields

This method returns XML as follows:

<CISWebService>

<StatusID>0</StatusID>

<Message>

<ImportResults>

<Request RequestID="3d90076f-002e-4111-bce3-d5b3fd3edf7f">

<QuoteID>0001827</QuoteID>

<InsuredID>219637</InsuredID>

</Request>

</ImportResults>

</Message>

</CISWebService>

Note: StatusID 0 = Success and StatusID 1= Failure

 

Exports AIM submission, version, and units at risk data. This includes named insured, submission data, version data, and units at risk information.

In AIM 6.5 the only units at risks data imported is general liability.

In AIM 6.5.1 the units at risk data imported is the above along with commercial property, crime, commercial inland marine, commercial package (general liability, commercial property, crime, and commercial inland marine), homeowner, and dwelling fire.

 

wsAcordXmlExport(pInputXML: String, tokenString: String): String

Input parameters

pQuoteID – quote ID to be returned

pVersion – version to be returned for the given quote ID

tokenString –authentication token returned by the WSLogin method

Details

  • Ÿ  If the quoteID passed in is bound the version of the quote returned will always is the bound version for that quoteid. No matter if a different version is requested.
  • Ÿ  If pVersion is not specified then the version returned will be the latest version for that submission/quote
  • Ÿ  If pVersion is not a valid version then an error is returned. An example follows: <example of error message>

Output fields

This method returns XML as follows:

<CISWebService>

<StatusID>0</StatusID>

<Message>

<?ACORD ACORD="1.20.0"?><ACORD>…</ACORD>

</Message>

</CISWebService>

<ACORD…</ACORD> – is the exported ACORD XML data

Standard Functions

The tables that follow show various functions used by AIM Web Service.

VerifyWSConnection(): String

Verifies a connection to AIM Web Service. If successful, returns the following message:

"CIS Web Service Connection Established (version x.x)."

This is the only function which does not require a security token and is used for testing purposes.

wsLogin(pNameHash: String, pPassHash: String): String:

Logon function for user authentication. Provide an MD5 hash of the user name and password. This function will authenticate and return a user token. This token is only valid for a limited amount of time. Programs that utilize AIM Web Services must take this into account. The token timeout is configurable in the provided configuration utility.

Input parameters

pNameHash, pPassHash

Output fields

tokenString – This is the security token which must be passed to all further Web Service function calls.

If the user cannot be authenticated, an empty string is returned.

wsLogin(pNameHash: String, pPassHash: String): String:

Logon function for user authentication. Provide an MD5 hash of the user name and password. This function will authenticate and return a user token. This token is only valid for a limited amount of time. Programs that utilize AIM Web Services must take this into account. The token timeout is configurable in the provided configuration utility.

Input parameters

pNameHash, pPassHash

Output fields

tokenString – This is the security token which must be passed to all further Web Service function calls.

If the user cannot be authenticated, an empty string is returned.

WSInsuredSearch(pInputXML: String, tokenString: String): String

Returns insured records based on search value (partial/full name) and producer/agentID. The producer/agent parameter can be left blank to return insured records for all producers/agents.

Input parameters

SearchValue, AgentID

Output fields

InsuredID, NamedInsured, City, State, Zip, Address1, Address2, Fax, Phone, DBAName

WSSubmissionSearch(pInputXML : String, tokenString: String): String

Returns submission status from view dvQuoteView for Insured ID and producer ID.

Input parameters

InsuredID, AgentID

Output fields

QuoteID, StatusName, CoverageName, Quoted, Effective

WSVerifyLogin(pInputXML: String, tokenString: String): String

Returns producer/agent ID from the taaWebAccess table given user ID and password.

Input parameters

UserName, Password

Output fields

UserID

WSEmailLoginInfo(pInputXML: String, tokenString: String): String

Returns user name and password from the taaWebAccess table e-mail address.

Input parameters

Email

Output fields

UserName, Password

WSProducerStatement(pInputXML: String, tokenString: String): String

Returns producer statement data based on producer/agent ID.

Input parameters

Date

Output fields

Company, policyID, namedinsured, invno, duedate, effective, bal, type, amt, agentcomm, agentcommamt, netdue, description, date

WSCompaniesUpdatedSince(pInputXML: String, tokenString: String): String

Returns company data for companies that have been updated since the input date. If the date is blank, returns all companies.

Input parameters

Date

Output fields

'name, companyID, dateadded, datemodified,' +

'address1, address2, city, state, zip, mailaddress1,' +

'mailaddress2, mailcity, mailstate, mailzip, ' + 'acctgaddress1,acctgaddress2,acctgcity,acctgstate, '+

'acctgzip, acctgphone, acctgfax, fax, phone, ' +

'acctgemail, email'

WSProducersUpdatedSince(pInputXML: String):

Returns producer data for producers that have been updated since the input date. If date is blank, returns all producers.

Input parameters

Date

Output fields

‘name, producerID, dateadded, datemodified,' +

'address1, address2, city, state, zip, mailaddress1,' +

'mailaddress2, mailcity, mailstate, mailzip, ' +

'acctgaddress1,acctgaddress2,acctgcity,acctgstate, '+

'acctgzip, acctgphone, acctgfax, fax, phone, ' +

'acctgemail, email’

WSProducerLookup(pInputXML: String, tokenString: String): String

Returns producer data for an agent ID.

Input parameters

AgentID

Output fields

name, address, city, state zip, mailaddress, mailcity, mailstate, mailzip, fax, phone

WSProducerPaymentInfo (pInputXML: String, tokenString: String): String

Returns producer payment data for a specified date range.

Input parameters

AgentID, BeginDate, EndDate

Output fields

CheckNo, Amount, Date, PayeeName

WSLocator(xml_input)

Returns an insured ID based on the input XML values:

Insured

If matching insured record is found, returns input XML with insured ID.

WSExecStoredProc (xml_input)

Reserved for future development.

Processes any stored procedure in the CIS database that is referenced in the stored procedure WSExecStoredProc. Returns stored procedure result set in XML format.

Custom Functions

WSImport(xml_input: String, tokenString: String) : String

Imports data to the database based on the method tag of the input XML.

Typical XML string:

<CISWebService>

</wsCISAIM>

<Transaction>

<Source>AGENCYNAME</Source>

<Type>AFD</Type>

<Method>Policy</Method>

<NamedInsured>Mary Policy2

</NamedInsured>

<DBAName>Policy Day Care</DBAName>

<InsuredID></InsuredID>

<Address1>1234 Some Street</Address1>

<Address2></Address2>

<City>San Antonio</City>

<State>TX</State>

<ZipCode>99999</ZipCode>

<Phone>(555)555-5555</Phone>

<Fax>(555)555-5555</Fax>

<Email>mary@certifieddaycare.com</Email>

<MailAddress1>1234 Some Street</MailAddress1>

<MailAddress2></MailAddress2>

<MailCity>San Antonio</MailCity>

<MailState>TX</MailState>

<MailZipCode>99999</MailZipCode>

<AcctExec></AcctExec>

<UserID></UserID>

<TerrorActApplies>Y</TerrorActApplies>

<Premium>310.00</Premium>

<Taxes>15.28</Taxes>

<Fees>0.32</Fees>

<Limits>25,000/50,000/5,000</Limits>

<Effective>01/31/2006</Effective>

<NumberOfChildren>10</NumberOfChildren>

<QuoteID></QuoteID>

<PolicyID></PolicyID>

</Transaction>

</wsCISAIM>

</CISWebService>

Valid Method values:

Application

Creates an application that a user may then view in AIM and process.

Insured

Creates an insured record.

Submission

Creates a quote and version record. If the InsuredID is blank, also creates an insured record.

Policy

Creates a Policy and Invoice record. If the InsuredID is blank, also creates an insured record. If the QuoteID is blank also creates a Quote and Version record. If the PolicyID is blank selects next available policy number from the register table.

Renewal

Renews a given Policy.

Renewal Quote

Renews a given quote (quote must be bound) returns the new quote ID as QuoteID.

The input need only contain those tags that are required for the method. For example, an input string for the renewal method could be:

<CISWebService>

</wsCISAIM>

<Transaction>

<Source>AGENCYNAME</Source>

<Type>AFD</Type>

<Method>Renewal</Method>

<PolicyID>FGL-30024471</PolicyID>

</Transaction>

</wsCISAIM>

</CISWebService>

The procedure will return an XML string containing the input values and include additional tags:

Status

0 = success

ReturnMessage

Sting indicating success or error.

Web Service XML Tags

The following is a list of valid XML tags, the methods in which they are used, their type and size, and whether they are required.

Tag

Method

Type

Required

Values

Source

All

char(15)

Y

Rothert

Type

All

char(4)

Y

CGL

Method

All

char(15)

Y

Application, Insured, Submission, Policy, Renewal, or RenewQuote

NamedInsured

Insured/Quote

char(151)

Y

DBAName

Insured/Quote

char(151)

N

Address1

Insured

Quote

char(40)

Y

N

Address2

Insured

Quote

char(40)

Y

N

City

Insured

Quote

char(28)

Y

N

State

Insured

Quote

char(4)

Y

N

ZipCode

Insured

Quote

char(14)

Y

N

MailAddress1

Insured

char(40)

N

MailAddress2

Insured

char(40)

N

MailCity

Insured

char(26)

N

MailState

Insured

char(4)

N

MailZip

Insured

char(14)

N

Phone

Insured

char(20)

N

Fax

Insured

char(20)

N

EMail

Insured

char(128)

N

Effective

Quote/RenewQuote/Policy

char(10)

N

(MM/DD/YYYY ) if not set, defaults to current date.

AcctExec

Quote/RenewQuote/Policy

char(8)

Y

User ID for acct. exec – see DMU -> Users -> User ID

Premium

Quote

Policy

float

N

Y

Numeric only (decimal point valid, if required)

CSR

Quote/Policy

char(8)

Y

User ID for CSR – see DMU -> Users -> User ID

TerrorActApplies

Quote/Policy

char(1)

Y

Y/N

Tax1

Quote

Policy

float

N

Y

Numeric only (decimal point valid, if required)

Tax2

Quote

Policy

float

N

Y

Numeric only (decimal point valid, if required)

Tax3

Quote

Policy

float

N

Y

Numeric only (decimal point valid, if required)

Tax4

Quote

Policy

float

N

Y

Numeric only (decimal point valid, if required)

TerActPremium

Quote

Policy

float

N

Y

Numeric only (decimal point valid, if required)

Fees

Quote

Policy

float

N

Y

Numeric only (decimal point valid, if required)

PolicyID

Renewal

char(25)

Y

QuoteID

RenewQuote/Renewal/Policy

char(10)

Y

InsuredID

Quote

integer

N

If not provided the quote method will create a new insured record

PolicyStatus

Policy

char(3)

Y

'PIF'

TotalAmount

Quote

float

N

Premium + Fees + Taxes

CompanyID

Quote/Policy

char(6)

Y

Risk company ID (see DMU -> Company -> ID)

MarketID

Quote/Policy

char(6)

Y

Market company ID (see DMU -> Company -> ID)

ProductID

Quote/Policy

char(8)

Y

Product ID (see DMU -> Products -> ID)

TaxCode1

Invoice

char(3)

N

(see DMU -> Invoicing -> Tax Table -> Tax Code ID)

PayToID1

Invoice

char(6)

N

(see DMU -> Invoicing -> Tax Table -> CompanyID)

TaxCode2

Invoice

char(3)

N

(see DMU -> Invoicing -> Tax Table -> Tax Code ID)

PayToID2

Invoice

char(6)

N

(see DMU -> Invoicing -> Tax Table -> CompanyID)

TaxCode3

Invoice

char(3)

N

(see DMU -> Invoicing -> Tax Table -> Tax Code ID)

PayToID3

Invoice

char(6)

N

(see DMU -> Invoicing -> Tax Table -> CompanyID)

TaxCode4

Invoice

char(3)

N

(see DMU -> Invoicing -> Tax Table -> Tax Code ID)

PayToID4

Invoice

char(6)

N

(see DMU -> Invoicing -> Tax Table -> CompanyID)

TaxDescription1

Invoice

char(95)

N

(see DMU -> Invoicing -> Tax Table -> Tax Code ID description)

TaxDescription2

Invoice

char(95)

N

(see DMU -> Invoicing -> Tax Table -> Tax Code ID description)

TaxDescription3

Invoice

char(95)

N

(see DMU -> Invoicing -> Tax Table -> Tax Code ID description)

TaxDescription4

Invoice

char(95)

N

(see DMU -> Invoicing -> Tax Table -> Tax Code ID description)

TerActGrossComm

Quote/Policy

float

N

TerActAgentComm

Quote/Policy

float

N

TerActStatus

Quote/Policy

char(14)

N

TerTaxes

Quote/Policy

float

N

FeeSchedule

Quote/Policy

char(254)

N

NameType

Insured

char(3)

Y

ProducerID

Insured/Quote

char(8)

Y

InvPremiumDescription

Invoice

char(95)

N

InvFeeDescription

Invoice

char(95)

N

InvFeeTransCD

Invoice

char(6)

N

MarketID

Quote

char(6)

Y

CoverageID

Quote

char(6)

Y

TeamID

Quote

char(8)

N

DivisionID

Quote

char(8)

N

QuoteDescription

Quote

char(120)

N

AgentComm

Quote

float

N

GrossComm

Quote

float

N

PolicyTerm

Quote

char(25)

N

Exposure

Quote

char(40)

N

Limit1

Quote

char(8)

N

Limit2

Quote

char(8)

N

Limit3

Quote

char(8)

N

Limit4

Quote

char(8)

N

Limit5

Quote

char(8)

N

Limit6

Quote

char(8)

N

Limit7

Quote

char(8)

N

Coverage1

Quote

char(100)

N

Coverage2

Quote

char(100)

N

Coverage3

Quote

char(100)

N

Coverage4

Quote

char(100)

N

Coverage5

Quote

char(100)

N

Coverage6

Quote

char(100)

N

Coverage7

Quote

char(100)

N

CertificateID

WSCertificate

integer

Y

CertHolderID

WSCertificate

integer

Y

Not required if adding new holder

HolderName

WSCertificate

char(150)

N

Required if adding new holder

HolderAddress1

WSCertificate

char(30)

N

Required if adding new holder

HolderAddress2

WSCertificate

char(30)

N

Required if adding new holder

HolderCity

WSCertificate

char(20)

N

Required if adding new holder

HolderState

WSCertificate

char(2)

N

Required if adding new holder

HolderZip

WSCertificate

char(9)

N

Required if adding new holder

HolderPhone

WSCertificate

char(14)

N

HolderFax

WSCertificate

char(14)

N

New Tags

Tag

Method

Type

Required

Values

MarketID

Quote

char(6)

N

if State in ('CA', 'NJ', 'NY') then 'RE0001' else 'RE0002'

ProductID

Quote/Policy

char(8)

N

if State in ('CA', 'NJ', 'NY') then 'AFDSGLST' else 'AFDSGLLA'

CompanyID

Quote/Policy

char(6)

N

if State in ('CA', 'NJ', 'NY') then 'RE0001' else 'RE0002'

TaxCode1

Invoice

char(3)

N

'SLT'

TaxID1

Invoice

char(6)

N

<State> + 'SLT' (ex. 'TXSLT' for Texas)

TaxCode2

Invoice

char(3)

N

'SOF'

TaxID2

Invoice

char(6)

N

<State> + 'SOF' (ex. 'TXSOF' for Texas)

TaxCode3

Invoice

char(3)

N

'MTX'

TaxID3

Invoice

char(6)

N

'MUNTX'

TaxCode4

Invoice

char(3)

N

'SSC'

TaxID4

Invoice

char(6)

N

'STSURG'

TerActGrossComm

Quote/Policy

float

N

TerrorActApplies = 'Y' then '23.0' else ''

TerActAgentComm

Quote/Policy

float

N

TerrorActApplies = 'Y' then '999.0' else ''

TerActStatus

Quote/Policy

char(14)

N

TerrorActApplies = 'Y' then 'Applies' else ''

TerTaxes

Quote/Policy

float

N

TerrorActApplies = 'Y' then '0.25' else ''

FeeSchedule

Quote/Policy

char(254)

N

'AFDS Purchasing Group Membership Fee $' + <Fees as char>

NameType

Insured

char(3)

N

'B'

ProducerID

Insured/Quote

char(8)

N

'GA89990'

InvPremiumDescription

Invoice

char(95)

N

'Commercial General Liability'

InvFeeDescription

Invoice

char(95)

N

'AFDS Purchasing Group Membership Fee'

InvFeeTransCD

Invoice

char(6)

N

'AFMB'

CoverageID

Quote

char(6)

N

'CGL'

TeamID

Quote

char(8)

N

'AF_1'

DivisionID

Quote

char(8)

N

'1'

QuoteDescription

Quote

char(120)

N

'Personal Care Services'

AgentComm

Quote

float

N

'0.0'

GrossComm

Quote

float

N

'23.00'

PolicyTerm

Quote

char(25)

N

'12 Months'

Exposure

Quote

char(40)

N

'# Children' (see note 1 below)

Limit1

Quote

char(8)

N

<Limit1> (see note 2 below)

Limit2

Quote

char(8)

N

'1,000'

Limit3

Quote

char(8)

N

'5,000'

Limit4

Quote

char(8)

N

'10,000'

Limit5

Quote

char(8)

N

<Limit1>

Limit6

Quote

char(8)

N

<Limit2>

Limit7

Quote

char(8)

N

<Limit2>

Coverage1

Quote

char(100)

N

'GENERAL LIABILITY EACH OCCURRENCE LIMIT'

Coverage2

Quote

char(100)

N

'MEDICAL EXPENSE PER PERSON LIMIT - Any One Person'

Coverage3

Quote

char(100)

N

'MEDICAL EXPENSE OCCURRENCE OR INCIDENT LIMIT - Any One Occurrence or Incident'

Coverage4

Quote

char(100)

N

'MEDICAL EXPENSE AGGREGATE LIMIT'

Coverage5

Quote

char(100)

N

'SEXUAL ABUSE OR MOLESTATION EACH'

Coverage6

Quote

char(100)

N

'SEXUAL ABUSE OR MOLESTATION AGGR

Coverage7

Quote

char(100)

N

'POLICY AGGREGATE LIMIT'

Notes

  1. Number of children is determined as follows:

if NumChildren in ('1', '2', '3', '4', '5', '6')

Set NumChildren = '6'

else if NumChildren in ('7', '8', '9', '10', '11', '12')

Set NumChildren = '12'

else set NumChildren = '18'

2. This is determined by the limits you are passing. For example: '25,000/50,000'

<Limit1> would be ’25,000’ and <Limit2> would be ’50,000’

3. Tags are case sensitive.

Concept Link IconSee Also