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 |
|
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 |
|
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 |
|
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 |
|
|
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
- 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.