Protocol Manual
Contents
1. bytesize Byte size if serially connected stopbits Stop bits if serially connected parity Parity if serially connected comp Compression YES or NO if modem connection errorcorr Error Correction YES or NO if modem connection FAILBACK FAILBACK sub operation facilitates releasing a previous manual failover invocation of the specified provider Format PROV FAILBACK provider coverage Status PROV STATUS statuscode statusmessage OUTPUT Item Description provider Provider name coverage Coverage name FAILOVER FAILOVER sub operation facilitates the manual failover invocation of the specified provider Format PROV FAILOVER provider coverage Status PROV STATUS statuscode statusmessage OUTPUT Item Description provider Provider name coverage Coverage name 38 FirstPAGE v9 Protocol Specification LIST LIST sub operation facilitates the interrogation of the known providers Format PROV LIST Status PROV STATUS statuscode statusmessage Result PROV RESULT 0 name1 coverage1 Result PROV RESULT 0 name2 coverage2 Result PROV RESULT 1 nameN coverageN OUTPUT Item Description name Provider name coverage Coverage name RELOAD The RELOAD sub operation indicates to the FirstPAGE Server that it should reload all internal tables related to providers Format PROV RELOAD Status PROV STATUS statuscode statusmessa2. 51 SeQent Real Time Decision Solutions LOGIN The LOGIN sub operation facilitates the authentication or identification of the user to the FirstPAGE Server engine If the engine is running in secure mode then the username and password must exist in the user table before the user may interact with FirstPAGE Server otherwise a new user record is created using default preferences If SECMODE is off then this record is only used to track user specific preferences and not for authentication In the instance of SECMODE authentication is Off then the login of Domain NCTI User ADMIN Pass ADMIN should be utilized Format USER LOGIN domain user password Status USER STATUS statuscode statusmessage INPUT Field Description domain Domain of user account Note If security mode is Ford Authentication then domain must be FORD user User account password Password PASSCHG The PASSCHG sub operation facilitates a client application changing the password of an authenticated user within the FirstPAGE Server engine Format USER PASSCHG oldpass newpass Status USER STATUS statuscode statusmessage INPUT Field Description oldpass newpass 52 FirstPAGE v9 Protocol Specification TYPE The TYPE sub operation facilitates a client application determining the type of user currently logged in Format USER TYPE Status USER STATUS statuscode statusmess
3. Text Signature to be used within FirstPAGE Client USERNAME Username Username of the logged in account GROUPLIST Text Comma separated list of associated destination groups 50 FirstPAGE v9 Protocol Specification DESTLIST The DESTLIST sub operation facilitates a client application to obtain the authenticated users destinations within the FirstPAGE Server engine If the engine is running in a secure mode then the user login for the user initiating this command must be an administrator if the optional domain and username parameters are specified Format USER DESTLIST domain username Status USER STATUS statuscode statusmessage Result USER RESULT eof destinationtype destinationname OUTPUT Item Description Destinationtype DestinationType 12destination 2 distribution list Destinationname Username of the user account LIST The LIST sub operation facilitates the listing of the known users that exist within the FirstPAGE Server engine If the engine is running in a secure mode then the user login for the user initiating this command must be an administrator Format USER LIST Status USER STATUS statuscode statusmessage Result USER RESULT eof domainname username usertype OUTPUT Item Description domainname Domain of the user account username Username of the user account usertype User type ADMIN or USER
4. major ver Major version complete_ver Complete version specification platform Platform specification start_datetime Date time the engine started specified in UCT RELOAD The RELOAD sub operation indicates to the FirstPAGE Server that it should reload all internal tables most likely because its database contents have been manipulated and it needs to make changes to its internal data structures as appropriate SeQent Real Time Decision Solutions Format ADMIN RELOAD Status ADMIN STATUS statuscode statusmessage SECMODE The SECMODE sub operation requests that the engine return details as to which security mode it is running under Format ADMIN SECMODE Status ADMIN STATUS statuscode statusmessage Result ADMIN RESULT 1 Secmode OUTPUT Field Description Secmode Security mode bitmask Bit 0 Authentication required Off 2 No authentication required On Authentication required Bit 1 4 Unused Bit 5 Ford Authentication Requires bit O be on Off Ford authentication off On Ford authentication on Bit 6 Chrysler Authentication Requires bit O be on Off Chrysler authentication off On Chrysler authentication on Bit 7 Windows Trusted Authentication Requires bit 0 be on Off 2 Windows Trusted authentication off On Windows Trusted authentication on SHUTDOWN The SHUTDOWN sub operation requests that the engine cleanly shutdown The engine will proceed cleanly disc
5. Ren RM 48 DESTLEIST uer ertet eerte eee eite e bier eee 51 EIST ar RR 51 LOGIN ions RR 52 PASSCGHG rettet exer exer A ei Goede eR ete ee e ee 52 c 53 WRITE eene e bebat tese oA See 53 TECHNICAL ASSISTAN UG E ees so eoa eo sao obe ooo een eae en eaa earn a ee sa 56 BA e UE EI NISI IRIS 56 SUPPORT CONTRACTS nenne 56 HE PAIDESK E tiet rE es Me ELE 56 GLOSSARY 57 EXAMPLE SESSIONS 4 eoo sao be bend ee ea pao ooa ino eerta a a een nae ei n aa eon 60 CONNECT LOGIN 60 SENDING MESSAGE A DESTINATION DL eere 60 LIST OF KNOWN DESTINATIONS ccccccecececececececececececececececececececececececeeesens 61 LIST OF KNOWN DISTRIBUTION LISTS aaa 61 SENDING MESSAGE TO A UNNAMED DESTINATION NETWORK ID 62 SeQent Real Time Decision Solutions Chapter One Protocol Overview This chapter introduces FirstPAGE protocol and describes how to utilize it from within your applications GY Refer to the FirstPAGE Server Installation and User manual for more details on the FirstPAGE Server product FirstPAGE v9 Protocol Specification Getting Started This manual contains procedural and conceptual information about the FirstPAGE Protocol It is written for System Administrators and Devel
6. account Format PDIST WRITE name notes pdest1 pdest2 pdestN Status PDIST STATUS statuscode statusmessage INPUT Item Description 35 SeQent Real Time Decision Solutions name notes pdest1 pdest2 pdestN 36 FirstPAGE v9 Protocol Specification Chapter Eleven PROV Operations This chapter describes the FirstPAGE protocol subset known as the PROV operations These commands allow the developer to request information on the service providers define in the FirstP AGE Server DETAIL The DETAIL sub operation facilitates the querying of a specific provider If the engine is able to locate the provider then its details are returned If it is unable to locate the provider an error will be returned Format PROV DETAIL provider coverage Status PROV STATUS statuscode statusmessage Result PROV RESULT 1 name coverage address speed maxsec maxtrans maxalpha maxnum protocol bytesize stopbits parity comp errorcorr INPUT Item Description provider Provider name to lookup coverage Coverage name to lookup OUTPUT Item Description name Name of provider coverage Coverage name of provider address speed maxsec maxtrans maxalpha Maximum alpha numeric length maxnum Maximum numeric length protocol Protocol name 37 SeQent Real Time Decision Solutions
7. specific destinations that users may maintain for providers defined within the FirstPAGE Server configuration DETAIL The DETAIL sub operation facilitates the querying of a specific personal destination s attributes If the engine is able to locate the specified personal destination then its details are returned If it is unable to locate the personal destination an error will be returned Format PDEST DETAIL destname Status PDEST STATUS statuscode statusmessage Result PDEST RESULT 1 nameltitle email provid netid tzid typeid notes INPUT Item Description destname Personal destination to lookup OUTPUT Item Description name Personal destination name title Title email Email address provid Provider 19 netid Network Id tzid Time Zone Id See DEST TZONES typeid Type Id See DEST TYPES notes Note entered 30 FirstPAGE v9 Protocol Specification INITIATE The INITIATE sub operation facilitates the initiation of messaging transactions within the engine If the engine is able to accept the specified transaction then a serial number for this transaction is returned This serial number may be used to monitor or cancel the request Format PDEST INITIATE destname message Status PDEST STATUS statuscode statusmessage Result PDEST RESULT 1 serialnumber INPUT Item Description destname Personal destination nam
8. them 1994 2014 SeQent All rights reserved Printed in Canada FirstPAGE is a trademark of SeQent Other brand and product names are trademarks or registered trademarks of their respective holders Document Date May 28 2014 FirstPAGE v9 Protocol Specification Edits Version Date Author Description 9 00 September 1 2008 S Burns C Initial prototype Longman D Viasm n Added DESTINATION field for USER DETAIL 9 01 December 1 2009 S Burns D Expanded USER DETAIL call to support admin Vlasman lookup of other user details 9 02 January 28 2011 S Burns Corrected USER DETAIL items to return dests and dist lists 9 03 February 4 2011 J Weber Added new protocol item USER DESTLIST and removed the destination details from the USER DETAIL call 9 04 April 26 2011 S Burns Added new protocol items PROV FAILOVER and PROV FAILBACK 9 05 May 3 2011 J Weber Added new PROV STATE command 9 07 Aug 12 2011 D Vlasman Add new Windows Trusted security mode 9 08 July 4 2012 S Burns Add USER TYPE command 9 09 August 4 2012 J Weber New PROV TRANSCOUNT 9 10 April 25 2013 S Burns Deprecated PAGE QUEUE Defined DEST QUEUE 9 11 May 23 2013 S Burns Clarify result packets Clarify recurrence items 9 12 June 24 2013 S Burns Clarify example session and dest calls 9 13 July 4 2013 J Weber Clarify DEST QUEUE injection 9 15 December 13 2013 S Burns Cla
9. CUR DETAIL serialnumber Status RECUR STATUS statuscode statusmessage Result RECUR RESULT 1 id username domain destination message sendtime type detail startdate rangetype nextsenddate prevs enddate range or date INPUT Item Description serialnumber OUTPUT Item Description id username domain destination message sendtime type detail startdate rangetype 41 SeQent Real Time Decision Solutions nextsenddate prevsenddate range or date LIST The LIST sub operation facilitates the interrogation of the known recurring transactions within the FirstPAGE Server for the currently logged in user account Format RECUR LIST Status RECUR STATUS statuscode statusmessage Result RECUR RESULT 0 recurid1 Result RECUR RESULT 0 recurid2 Result RECUR RESULT 1 recuridN OUTPUT Item Description recurid1 recurid2 recuridN 42 FirstPAGE v9 Protocol Specification REMOVE The REMOVE sub operation facilitates the removal of a recurring transaction within the FirstPAGE Server for the currently logged in user account Format RECUR REMOVE serialnumber Status RECUR STATUS statuscode statusmessage INPUT Item Description serialnumber WRITE The WRITE sub operation facilitates the initiation of a new recurring transaction within the FirstPAGE Server for the current
10. EOADE 5 Aste ner eun i nb i IET od 18 ATTRIB OPERATIONS 19 IBN 19 OPERATIONS wissisessscsscconssssnscasccsescoissvessoscesecsosscveessbesbesesbubisessoedecssies 20 Bice arnt ce met 20 RBMON E E A E A S A k ee 20 WREDE eb snnt ete ch pt ndi teres 21 DEST OPERATIONS eese eese et too eae rone ein ER ae ep PF Poe essa e ee ERR a oe eo e ez o ne 22 DETAID x er ERN ERR EI 22 Hi IEEE edn di beden O E EE ena velja 23 MIS EES E E EA EEEE be jv dob 23 6187210 c 24 RBLOAD utt ES XN EE UTR e NE ERR TREE TENES 25 TYPES E 25 ete e eet tes vov iunio en 25 SeQent Real Time Decision Solutions DIST OPERATIONS 26 INCAT E 26 DETA ge cas 27 LIST aot tu Eu ardet ne teme se atate AI 27 RELOAD rn 27 GROUP OPERATIONS eere non seno on seno nena 28 DETAIL tere eret E 28 LIST ees eee tert eie oe 28 RELOAD ees earl Ne e eeepc ER 29 PDEST OPERATIONS sesto sees sonata 30 MO VAY RE RE NA ENE NR 30 INITIATE 31 31 REMOVE 32 WRITE ceecee osere edee seere Eri E EEE EEES E EEE zgane E 32
11. PDIST OPERATIONS eese esee eese nanesena nn seta sens tassa ona asane na snae 33 DETAIL P 33 eei etre ret rete irre ciet te bur neis epe tier A eb 34 e OE O RO RO 35 REMON 35 b dup ie A 35 PROV OPERATIONS cscsscssssssssssssssssssessessssessessssessessssessessrsessessnsesseseesesees 37 DETAIL Bis et ee eee 37 PAILBACK BWR Gino niet 38 FAILOVER UNI 38 E 39 RELOAD casts asc eased SR BEREICHE 39 STATE es Seb A PRA DASS 39 TRANSCOUN nS aD a ENEM SNOS ee i 40 RECUR OPERATIONS eese eese enne tn enses tatus n statu stas non sins 41 DETAM 41 BE E 42 REMOVE vise tak ve ka 43 WRITE EEA A RE ENE 43 SESSION esee eese tnnt n etn 45 WRITE 45 FirstPAGE v9 Protocol Specification TRANS OPERA TIONS 46 m 46 EIS Tode a eS 46 USER OPERA TIONS 48 PETA ATI
12. SeQent Real Time Decision Solutions FirstPAGE v9 19 Protocol Specification SeQent Suite 137 4500 Blakie Road London Ontario Canada N6L 1G5 SeQent Real Time Decision Solutions Terms of Use Information in this document is subject to change without notice and does not represent a commitment on the part of SeQent The software which includes information contained in any databases described in this document is furnished under a license agreement or nondisclosure agreement and may be used or copied only in accordance with the terms of the agreement It is against the law to copy the software on any medium except as specifically allowed in the license or nondisclosure agreement No part of this manual may be reproduced or transmitted in any form or by any means electronic or mechanical including photocopying and recording for any purpose without the express written permission of SeQent This software program and associated documentation are provided in an as is condition In no event shall SeQent its employees directors or agents be liable for any loss or damage whatsoever including but not limited to damages for loss of business profits business interruption loss of business information or other monetary loss arising out of the use of or the inability to use this software By installing this software on your computer system you acknowledge that you have read and understood these terms and that you accept
13. ULT 1 OUTPUT Item Description dest Name title Title type Destination type See DEST TYPES netid Network ID al Alias 1 a2 Alias 2 a3 Alias 3 loc Locator QUEUE The QUEUE sub operation facilitates the direct injection of transactions into a providers queue If it is unable to locate the provider coverage an error will be returned If the engine is able to accept the specified transaction then a serial number for this transaction is returned This serial number may be used to monitor or cancel the request Format DEST QUEUE provider coverage networkid msg Status DEST STATUS statuscode statusmessage Result DEST RESULT 1 serialnumber INPUT Item Description provider Provider name coverage Coverage name networkid Network Id msg Message text Note and must be escaped OUTPUT Item Description serialnumber Assigned serial number 24 FirstPAGE v9 Protocol Specification RELOAD The RELOAD sub operation indicates to the FirstPAGE Server that it should reload all internal tables related to destinations Format DEST RELOAD Status DEST STATUS statuscode statusmessage LYPES The TYPES sub operation facilitates the interrogation of the known destination types that exist within the FirstPAGE Server engine Format DEST TYPES Status DEST STATUS statuscode statusmessage Result DEST RESULT O type
14. USER STATUS statuscode statusmessage Result USER RESULT 0 item1 item1 value Result USER RESULT 0 item2 item2value Result USER RESULT 1 itemN itemNvalue INPUT Item Description Domain Domain name optional Username User name optional OUTPUT Item Value s Notes DESTINATION destinationname Destination m name s Odistlistname associated with 48 FirstPAGE v9 Protocol Specification this user account Not returned if there are no associated destinations DLs There may be many of these values Prefixed with A if a distribution list HONORSCHED ON OFF Status of destination schedule honouring IDLEMINUTES 0 99 0 GUI will never lock 1 99 GUI will lock out after x minutes requiring user to re authenticate to continue LOGONDOMAIN domainname Domainname of the account SECURITYLEVEL Security level value SIGENVVAR Environment variable name If SIGSTATE 1 then the contents of this client side environment variable will be used by FirstP AGE Client for the signature 49 SeQent Real Time Decision Solu SIGMETHOD 0 2 0 Signature provided by client 1 Signature retrieved from environment variable specified in SIGENVVAR 2 Signature is authenticated username SIGSTATE 0 1 0 Signature is off 1 Signature is on SIGVALUE
15. age Result USER RESULT eof usertype OUTPUT Field Description usertype One of USER or ADMIN WRITE The WRITE sub operation facilitates the setting of user preferences within the FirstPAGE Server engine At this time the following values are supported Item Value s Notes DESTINATION destinationname Destination name associated with this user account Blank if no associated destination Note Should not be listed as available for USER WRITE Once moved to USER DETAIL then remove it here HONORSCHED ON OFF Determine if destination schedules should be 53 SeQent Real Time Decision 5 honoured SIGVALUE Text Signature to be used within FirstPAGE Client SIGMETHOD 0 2 0 Signature provided by client 1 Signature retrieved from environment variable specified in SIGENVVAR 2 Signature is authenticated username SIGSTATE 0 1 0 Signature is off 1 Signature is on SIGENVVAR Environment variable name If SIGSTATE 1 then the contents of this client side environment variable will be used by FirstPAGE Client for the signature IDLEMINUTES 0 99 0 GUI will never lock 54 FirstPAGE v9 Protocol Specification 1 99 GUI will lock out after x minutes requiring user to re authenticate to continue Format USER WRITE item value Stat
16. be HONORSCHED and its value may be ON or OFF or RETRIES and a count of gt 1 and lt 10 If HONORSCHED is set to ON then any schedule for a destination will be honoured If OFF the schedule will be ignored and the destination will be sent any message regardless of the time of day RETRIES value is an integer representing the number of times the message will be attempted to be delivered to the provider Format SESSION WRITE item value Status SESSION STATUS statuscode statusmessage INPUT Item Description Item HONORSCHED or RETRIES Value HONORSCHED ON or OFF RETRIES Integer value gt 1 lt 10 45 SeQent Real Time Decision Solutions Chapter Fourteen TRANS Operations This chapter describes the FirstPAGE protocol subset known as the TRANS operations These commands allow the developer to request transaction information from the engine regarding transactions previously initiated DETAIL The DETAIL sub operation facilitates the querying of a specific transaction s attributes If the engine is able to locate the specified transaction then its details are returned if it is unable to locate the transaction an error will be returned Format TRANS DETAIL serialnumber Status TRANS STATUS statuscode statusmessage updatetime Result TRANS RESULT 1 status INPUT Item Description serialnumber Transaction number of DEST INITIATE OUTPUT Item Desc
17. ct amp Login Initiate a message to 5195551212 Performed once for each destination to be notified Ensure the status value is 0 before looking for response with transaction serial number this example the named provider in FirstPAGE Server is BELLMOB and coverage is CANADA DEST QUEUE BELLMOB CANADA 5195551212 pTXT BELLMOBILITY CA Jim lets meet for lunch at 13 00 Franks DEST STATUS 0 Success DEST RESULT 1 VM220035800240067 62
18. d serial number NOTE Distribution list initiates utilize the DEST function rather than the DIST function 26 FirstPAGE v9 Protocol Specification DETAIL The DETAIL sub operation facilitates the querying of a specific distribution lists members If the engine is able to locate the specified distribution list then its details are returned If it is unable to locate the distribution list an error will be returned Format DIST DETAIL name Status DIST STATUS statuscode statusmessage Result DIST RESULT 0 desi title email note Result DIST RESULT 1 INPUT Item Description name Name of destination to lookup LIST The LIST sub operation facilitates the interrogation of the known distribution lists Format DIST LIST Status DIST STATUS statuscode statusmessage Result DIST RESULT 0 dist description Result DIST RESULT 1 OUTPUT Item Description dist Distribution list name description Description RELOAD The RELOAD sub operation indicates to the FirstPAGE Server that it should reload all internal tables related to distribution lists Format DIST RELOAD Status DIST STATUS statuscode statusmessage 27 SeQent Real Time Decision Solutions Chapter Eight GROUP Operations This chapter describes the FirstPAGE protocol subset known as the GROUP operations These commands allow the developer to request information on d
19. e message Message text Note and must be escaped OUTPUT Item Description serialnumber Serial number assigned to transaction LIST The LIST sub operation facilitates the interrogation of the known destinations that exist within the FirstPAGE Server engine for the currently logged in user Format PDEST LIST Status PDEST STATUS statuscode statusmessage Result PDEST RESULT 0 destination1 Result PDEST RESULT 0 destination2 Result PDEST RESULT 1 destinationN OUTPUT Item Description destination1 ie personal destination name destination2 2 personal destination name destinationN N personal destination name 31 SeQent Real Time Decision Solutions REMOVE The REMOVE sub operation facilitates the removal of a personal destination within the FirstPAGE Server for the currently logged in user account Format PDEST REMOVE name Status PDEST STATUS statuscode statusmessage INPUT Item Description name Personal destination name to remove WRITE The WRITE sub operation facilitates the creation of a new Or update of an existing personal destination within the FirstPAGE Server for the currently logged in user account Format PDEST WRITE namefltitle email provid netid tzid typeid destinationtypeid notes Status PDEST STATUS statuscode statusmessage INPUT Item Description name title email provid netid tzid typeid destinationtype
20. e Numeric Length property of a provider provides the same functionality as the Alpha Length property 58 FirstPAGE v9 Protocol Specification Provider A FirstPAGE Server provider is a name assigned to the configuration information required to connect to a messaging service provider Schedule A FirstPAGE Server schedule is a name assigned to a set of weekday configuration rules which define the times during which a destination may receive messages A schedule once defined may then be assigned to a destination over a time period 59 SeQent Real Time Decision Solutions Example Sessions Before attempting to use any of these interfaces please be sure to read the Packet Format section of Chapter 2 Connect amp Login Confirm FirstPAGE Server Connection Performed one time when first connecting the socket Ensure the 4 parameter in the 2 response is FirstPAGE Server ADMIN DETAIL ADMIN STATUS 0 Success ADMIN RESULT 1 FirstPAGE Server VM2W2K3SE2 9 v9 08 1 0 IX86 Win32 2013 06 20 18 3 1 00 Login to Generic Account Performed one time when first connecting the socket Ensure the status value returned is 0 USER LOGIN NCTI ADMIN ADMIN USER STATUS 0 Success Sending Message to a Destination DL Perform Connect amp Login Initiate a message to Jim s Phone Performed once for each destination to be notified Ensure the status value is 0 before looking for response with tran
21. ee DEST TZONES type Destination type See DEST TYPES note Note on the destination id Destination id 22 FirstPAGE v9 Protocol Specification INITIATE The INITIATE sub operation facilitates the initiation of messaging transactions within the engine If the engine is able to accept the specified transaction then a serial number for this transaction is returned This serial number may be used to monitor or cancel the request Format DEST INITIATE destname message Status DEST STATUS statuscode statusmessage Result DEST RESULT 1 serialnumber INPUT Item Description destname Destination name message Message text Note and must be escaped OUTPUT Item Description serialnumber Assigned serial number Format DEST INITIATE Qdistlistname message Status DEST STATUS statuscode statusmessage Result DEST RESULT 1 serialnumber INPUT Item Description distlistname Distribution list name message Message text Note and must be escaped OUTPUT Item Description serialnumber Assigned serial number LIST The LIST sub operation facilitates the interrogation of the known destinations that exist within the FirstPAGE Server engine Format DEST LIST 23 SeQent Real Time Decision Solutions Status DEST STATUS statuscode statusmessage Result DEST RESULT 0 desi title type netid a1 a2 a3 loc Result DEST RES
22. estination groups defined within the FirstPAGE Server DETAIL The DETAIL sub operation facilitates the querying of a specific group s members If the engine is able to locate the specified group then its details are returned If it is unable to locate the group an error will be returned Format GROUP DETAIL name Status GROUP STATUS statuscode statusmessage Result GROUP RESULT 0 DestID Result GROUP RESULT 0 DestID2 Result GROUP RESULT 1 DestIDN INPUT Item Description name Group name OUTPUT Item Description DestlD DestlD2 DestlDN LIST The LIST sub operation facilitates the interrogation of the known groups Format GROUP LIST Status GROUP STATUS statuscode statusmessage 28 FirstPAGE v9 Protocol Specification Result GROUP RESULT 0 group descr Result GROUP RESULT 1 OUTPUT Item Description group Group name descr Description RELOAD The RELOAD sub operation indicates to the FirstPAGE Server that it should reload all internal tables related to groups Format GROUP RELOAD Status GROUP STATUS statuscode statusmessage 29 SeQent Real Time Decision Solutions Chapter Nine PDEST Operations This chapter describes the FirstPAGE protocol subset known as the PDEST operations These commands allow the developer to initiate and manage personal destination transactions Personal destinations are user
23. ge STATE STATE sub operation facilitates querying the failover state of the specified provider Format PROV STATE provider coverage Status PROV STATUS statuscode statusmessage Result PROV RESULT 1 FAILOVERSTATE failoverstate OUTPUT tem Description Provider name coverage Coverage name 39 SeQent Real Time Decision Solutions failoverstate 0 normal 1 automatic 2 manual TRANSCOUNT TRANSCOUNT sub operation facilitates querying the number of transactions in the queue of the specified provider Format PROV TRANSCOUNT provider coverage Status PROV STATUS statuscode statusmessage Result PROV RESULT 1 QUEUESIZE transcount sizekB OUTPUT Item Description provider Provider name coverage Coverage name transcount Number of transactions in queue sizekB Size of queue in kilobytes 40 FirstPAGE v9 Protocol Specification Chapter Twelve RECUR Operations This chapter describes the FirstPAGE protocol subset known as the RECUR operations These commands allow the developer to submit modify and remove recurring message transactions from the engine DETAIL The DETAIL sub operation facilitates the querying of a specific recurring transaction s attributes If the engine is able to locate the specified transaction then its details are returned if it is unable to locate the transaction an error will be returned Format RE
24. he available services offered by the server engine An example of a client tool would be FirstPAGE Client which presents the user with a list of known messaging destinations and allows them to send messages to one or more destinations Coverage The coverage property of a provider is a name assigned to reflect the geographical area that this connection to the service provider allows you to send message too Usually for example in the case of dial up modem connection to service providers a different phone number is provider for each city The coverage field provides the administrator an easy method of tracking all of the different coverage areas a single provider is supporting Destination A FirstPAGE Server destination is a name assigned to a messaging location to which text messages may be delivered Ex SCOTTS PAGER KENS PHONE JIMS EMAIL Device A FirstPAGE Server device is a name assigned to a physical connection point on the server that will be used to establish a connection with a service provider Distribution List 57 SeQent Real Time Decision Solutions A FirstPAGE Server distribution list is a collection of destinations that can be sent a message with a single transaction Similar to an e mail distribution list a client that initiates a transaction with a distribution list will automatically send the same message to all associated destinations Engine An engine component implements a unified interface to a set
25. id notes 32 FirstPAGE v9 Protocol Specification Chapter Ten PDIST Operations This chapter describes the FirstPAGE protocol subset known as the PDIST operations These commands allow the developer to initiate and manage personal destination distribution list transactions Personal destination distribution lists are user specific distribution lists that users may maintain for providers defined within the FirstPAGE Server configuration DETAIL The DETAIL sub operation facilitates the querying of a specific personal distribution s attributes If the engine is able to locate the specified personal distribution list then its details are returned If itis unable to locate the personal distribution list an error will be returned Format PDIST DETAIL distname Status PDIST STATUS statuscode statusmessage Result PDIST RESULT 0 DestID Result PDIST RESULT 0 DestID2 Result PDIST RESULT 1 DestIDN INPUT Item Description distname Personal distribution list name to retrieve details for OUTPUT Item Description DestlD DestID2 DestIDN 33 SeQent Real Time Decision Solutions INITIATE The INITIATE sub operation facilitates the initiation of messaging transactions within the engine If the engine is able to accept the specified transaction then a serial number for this transaction is returned This serial number may be
26. ld Description Notes SeQent Real Time Decision Solutions RESULT A static value always included ina RESULT packet to indicate its type eofflag End of File flag 1 if this is the last RESULT packet 0 if more will follow data Operation Sub Op specific data cr ASCII Dec 13 Note The character as it is used as the protocol field separator must be escaped if it is used within a field To accomplish this prefix any 5 character with a V character and escape any V character with another character FirstPAGE v9 Protocol Specification Chapter Three ADMIN Operations This chapter describes the FirstPAGE protocol subset known as the ADMIN operations These commands typically only used by administration tools allow the developer to request information about the FirstPAGE Server status force engine reload These commands are not normally referenced by FirstPAGE gateways DETAIL The DETAIL sub operation requests that the engine return certain details to allow the administrator to determine which version is running Format ADMIN DETAIL Status ADMIN STATUS statuscode statusmessage Result ADMIN RESULT 1 FirstPAGE Server hostname major_ver complete_ver platform start_datetime OUTPUT Field Description Server Name Always FirstPAGE Server hostname Host name of the server running the server
27. ly logged in user account Format RECUR WRITE recurid dest msg time type details start rangetype lt optional rangevalue gt Status RECUR STATUS statuscode statusmessage Result RECUR RESULT 1 recurid INPUT Item Description recurid Serial number of recurrence to update 1 to create new dest Destination name msg Message text Time hh mm of when recurrence sends 24 hour format type 1 Daily 2 Weekly 3 Monthly 4 Yearly details lt OPT gt Option number lt EVERY x gt Every x 9 lt DOW xxx gt Day of week ie SUN FRI 43 SeQent Real Time Decision Solutions lt MONTH gt Month number Jan 1 lt DAY gt Day of the month Options Type Item Description Daily lt OPT 1 gt Every weekday Daily lt OPT 2 gt Every x days Weekly lt OPT 1 gt Every one of the specified DOW Monthly lt OPT 1 gt Day x of every y months Monthly lt OPT 2 gt xth DOW of every y months Yearly lt OPT 1 gt Every day x of month y Yearly lt OPT 2 gt xth DOW of MONTH 44 FirstPAGE v9 Protocol Specification Chapter Thirteen SESSION Operations This chapter describes the FirstPAGE protocol subset known as the SESSION operations These commands allow the developer to set session options WRITE The WRITE sub operation facilitates the setting of various values for the user session Item may
28. name display Result DEST RESULT 1 OUTPUT Item Description type Type Number eg 1 name Type Name eg ALPHAPAGER display Display Name eg Alpha Pager TZONES The TZONES sub operation facilitates the interrogation of the known destination time zones that exist within the FirstPAGE Server engine Format DEST TZONES Status DEST STATUS statuscode statusmessage Result DEST RESULT 0 zoneid name display Result DEST RESULT 1 OUTPUT Item Description zoneid Zone id name Name display Display name 25 SeQent Real Time Decision Solutions Chapter Seven DIST Operations This chapter describes the FirstPAGE protocol subset known as the DIST operations These commands allow the developer to manipulate transactions involving distribution lists INITIATE The INITIATE sub operation facilitates the initiation of distribution list transactions within the engine If the engine is able to accept the specified transaction then a serial number for this transaction is returned This serial number may be used to monitor or cancel the request Format DIST INITIATE distlist message Status DIST STATUS statuscode statusmessage Result DIST RESULT 1 serialnumber INPUT Item Description distlistname Distribution list name Message Message text Note and must be escaped OUTPUT Item Description Serialnumber Assigne
29. number 8003 To connect to the engine the user must open a TCP IP socket to the appropriate IP host using this port After this connection is completed the USER LOGIN operation must be performed Once the connection is open the user may begin to execute the commands indicated below You may opt to maintain this connection or it may be open and closed for each transaction if the application is not robust enough to provide reconnect on loss of this connection Disconnecting from the Server When the application is finished with the FirstPAGE Server any open connections to the server should first be closed SeQent Real Time Decision Solutions Object Terminology Within this document the following acronyms as detailed in the glossary will be utilized Term Description Destination Message end point ona service provider ie a mobile handset Provider Messaging service provider ie mobile carrier in house paging system etc Packet Formats All packets sent to and from the FirstPAGE Server follow a standard format Note that STATUS results MUST be read from the socket before performing the next operation If results are provided they must also always be read A standard transaction follows the following convention Client operation sub op data lt cr gt Server operation STATUS code message lt cr gt Field Description Notes Operation The operation family being req
30. of common related protocols The engine provides services to clients and gateways such that a common interface may be used to manipulate many different types of devices Engines are administered via Administrator components and are utilized by clients gateways or use written components Gateway A gateway component creates a bridge between a third party product anda standard NETCON server Typically an engine this component provides a conduit for forwarding events from the third party product into a NETCON standard server An example of a gateway would be an interface to an HMI or SCADA system forwarding events from that system to FirstPAGE Alarm Manager for processing An example of a gateway is Marquee Manager Gateway for VisualPlant This gateway forwards VisualPlant incidents to Marquee Manager Group A FirstPAGE Server group is a name assigned to a collection of destinations that are logically connected Groups are used by FirstPAGE Server clients to limit the destinations which are available for use Network ID A destination network id is the identifier the messaging network requires to remit a message to an end destination Similar to a phone number a network id can be any NETCON Technologies number of numbers alphabetic characters or a combination of the two For TAP connected providers the network id is usually a numeric value For SMTP connected providers the network id is the devices assigned e mail address Numeric Length Th
31. onnect from all providers and log any unsent messages Format ADMIN SHUTDOWN FirstPAGE v9 Protocol Specification Status ADMIN STATUS statuscode statusmessage SeQent Real Time Decision Solutions Chapter Four ALIAS Operations This chapter describes the FirstPAGE protocol subset known as the ALIAS operations These commands allow the developer to request alias information from the FirstPAGE Server LIST The LIST sub operation facilitates the interrogation of the known aliases Format ALIAS LIST Status ALIAS STATUS statuscode statusmessage Result ALIAS RESULT 0 alias1_a alias1_b alias1_c alias1_ locator Result ALIAS RESULT O alias2 a alias2 b alias2 c alias2 locator Result ALIAS RESULT 1 aliasN a aliasN b aliasN c aliasN locator RELOAD The RELOAD sub operation indicates to the FirstPAGE Server that it should reload all internal tables related to aliases Format ALIAS RELOAD Status ALIAS STATUS statuscode statusmessage FirstPAGE v9 Protocol Specification Chapter Five ATTRIB Operations This chapter describes the FirstPAGE protocol subset known as the ATTRIB operations These commands typically only used by administration tools allow the developer to request information about the FirstPAGE Server These commands are not normally referenced by FirstPAGE gateways LIST The LIST sub operation requests that the engine return certain details to allow the administrato
32. opers to enable them to utilize FirstP AGE from within their applications While it is not required that the user have any prior programming or alarm management experience the user should understand basic Windows concepts SeQent Real Time Decision Solutions Documentation Conventions This document contains the following documentation conventions to help you navigate through the manual obtaining a better understanding of the material L e Notes contain tips or reminders about procedural and conceptual information within the manual A e Cross references provide you with a link to further information about the section of the document that you are currently reading FirstPAGE v9 Protocol Specification Chapter Two FirstPAGE Server This chapter describes FirstPAGE Server fundamentals that the application developer should know before attempting to develop a FirstP AGE enabled application Server Engine FirstP AGE Server is a Windows service that provides an advanced interface for managing wireless message notifications To interface with the engine applications indicate which host they are running on which application they are and what alarm from their environment is now active or inactive This document will describe these items in detail so that the developer may form the correct packets to achieve the desired results Connecting to the Server FirstP AGE Server listens by default on TCP IP port
33. r to determine which version is running The parameter following list defines which items to return Format ATTRIB LIST item Status ATTRIB STATUS statuscode statusmessage Result ATTRIB RESULT 0 item data1 Result ATTRIB RESULT 0 item data2 Result ATTRIB RESULT 1 item dataN Valid items are INPUT Item Description SAPIOUT Known SAPI output device names SAPIVOICE Known SAPI voices OUTPUT Item Description item data1 Name of 1 output device or voice item data2 Name of 279 output device or voice item dataN Name of N output device or voice SeQent Real Time Decision Solutions Chapter Five CMSG Operations This chapter describes the FirstPAGE protocol subset known as the CMSG operations These commands allow the developer to manipulate common message lists LIST The LIST sub operation facilitates the interrogation of the known common messages for the currently logged in account Format CMSG LIST Status CMSG STATUS statuscode statusmessage Result CMSG RESULT 0 msgid1 message1 Result CMSG RESULT 0 msgid2 message2 Result CMSG RESULT 1 msgidN messageN OUTPUT Item Description msgid 1 message1 msgid2 message2 msgidN messageN REMOVE The REMOVE sub operation facilitates the removal of a personal common messages within the FirstPAGE Server for the currently logged in user account Format CMSG REMOVE m
34. rify TRANS DETAIL 9 16 April 24 2014 E Jones Added GROUPLIST field for USER DETAIL 9 17 May 11 2014 S Burns Clarify SESSION WRITE RETRIES SeQent Real Time Decision Solutions 9 18 May 21 2014 J Weber Corrected SESSION WRITE RETRIES description 9 19 May 28 2014 S Burns Clarified in secure server login account case FirstPAGE v9 Protocol Specification Table of Contents PROTOCOL OVERVIEW eeeece sevn veseeos eaie erbe een seo be peni even a euin reo een 8 GETTING STARTED ooo eto enar o eoe edo ro reo ERE SE Fe e eh Pe URS o aae PERSE E 9 DOCUMENTATION CONVENTIONS eene ee ee 10 FIRSTPAGE SERVER iieeeeoes saos ea ee sn och esae ck dabo oo re en ae paa Oe ee Uo aae oo sona Ee a eas 11 SERVER ENGINE te 11 CONNECTING TO THE SERVER ee 11 DISCONNECTING FROM THE SERVER 11 OBJECT TERMINOLOGY ccccccececececececececececececececececececsesesceceeececececeeeeeeeeess 12 ene eee tte cce id 12 ADMIN OPERATIONS e neeee sets ei eoe e ea oa eva E Ua e vie 15 DETAIL EINER IR MI NU d 15 RELOAD iz Nerd RERO ER Re PIRE DUI P P PI UIS 15 SEGMOPDPE ee ERR neu Nini line NI 16 SHUTDOWN RING NENNEN D eh ded ees 16 ALIAS OPERATIONS 18 IM EE 18 RB
35. ription status Most recent status code of transaction statusmessage Most recent status message of transaction updatetime Most recent status update date time GMT LIST The LIST sub operation facilitates the interrogation of the known transactions within the FirstPAGE Server for the currently logged in user account All transactions for which a status is known are returned 46 FirstPAGE v9 Protocol Specification Format TRANS LIST Status TRANS STATUS statuscode statusmessage Result TRANS RESULT 0 serialnumber1 Result TRANS RESULT 0 serialnumber2 Result TRANS RESULT 1 serialnumberN OUTPUT Item Description serialnumber1 serialnumber2 serialnumberN 47 SeQent Real Time Decision Solutions Chapter Fifteen USER Operations This chapter describes the FirstPAGE protocol subset known as the USER operations These commands allow the developer to define user options and obtain status DETAIL The DETAIL sub operation facilitates a client application to obtain the authenticated users preferences within the FirstPAGE Server engine The items returned are listed in the table found under the WRITE sub op within the USER operations If the engine is running in a secure mode then the user login for the user initiating this command must be an administrator if the optional domain and username parameters are specified Format USER DETAIL domain username Status
36. saction serial number DEST INITIATE JIMSPHONE Jim lets meet for lunch at 13 00 Franks DEST STATUS 0 Success DEST RESULT 1 VM220035800240065 60 FirstPAGE v9 Protocol Specification Initiate a message to the distribution list for telecom team Performed once for each destination to be notified Ensure the status value is 0 before looking for response with transaction serial number DEST INITIATE TELECOM Are are all going to meet for lunch at 13 00 Franks DEST STATUS 0 Success DEST RESULT 1 VM220035800242341 List of Known Destinations Perform Connect amp Login Request List of Known Destinations Performed once to obtain list of all known destinations RESULT 1 when list is complete Ensure the status value is 0 before looking for response with list of destination names DEST LIST DEST STATUS 0 Success List of Known Distribution Lists Perform Connect amp Login Request List of Known Distribution Lists Performed once to obtain list of all known distribution lists RESULT 1 when list is complete Ensure the status value is 0 before looking for response with list of distribution list names DIST LIST DIST STATUS 0 Success DIST RESULT 0 PAINTSHOP Paint shop staff 61 SeQent Real Time Decision Solutions DIST RESULT 0 ITSUPPORT IT Support Team DIST RESULT 1 FINANCE Finance Members Sending Message to a Unnamed Destination Network ID Perform Conne
37. sgid Status CMSG STATUS statuscode statusmessage 20 FirstPAGE v9 Protocol Specification INPUT Item Description msgid WRITE The WRITE sub operation facilitates the creation of a new personal common messages within the FirstPAGE Server for the currently logged in user account Use 1 for new messages existing msgid for updates Format CMSG WRITE msgid message Status CMSG STATUS statuscode statusmessage INPUT Item Description msgid message 21 SeQent Real Time Decision Solutions Chapter Six DEST Operations This chapter describes the FirstPAGE protocol subset known as the DEST operations These commands allow the developer to request alarms be initiated or terminated within the engine DETAIL The DETAIL sub operation facilitates the querying of a specific destination s attributes If the engine is able to locate the specified destination then its details are returned if it is unable to locate the destination an error will be returned Format DEST DETAIL destname Status DEST STATUS statuscode statusmessage Result DEST RESULT eof dest titlelemail pid nid tzid type note id INPUT Item Description destname Destination name to lookup OUTPUT Item Description dest Destination name title Destination title email Destination email pid Provider id nid Network Id tzid Time zone Id S
38. uested sub op The sub operation within the operation family desired Data Any optional data required for the operation sub op to FirstPAGE v9 Protocol Specification be executed STATUS A static value always included in a STATUS packet to indicate its type Code The status code 0 Success resulting from the execution of the Non 0 operation sub option Error Failure Message The status message explaining the reason for the status code Cr ASCII Dec 13 For extended status commands the format above is consistent but one or more result packets may follow Result packets will only be returned for commands that need to return more data to the client than just a status code Results will only be returned if the code value of the STATUS packet is 0 which indicates the command was a success The format of an extended transaction is as follows Client operation sub op data lt cr gt Server operation STATUS 0 message lt cr gt Server operation RESUL T eofflag data cr For the RESULT packet the eofflag will be 0 if another result packet will follow or 1 if this is the last result packet The data portion of the packet is specific to the command being executed and the trailing is always provided All results MUST be read until the RESULT 1 packet is received until the final lt cr gt character Fie
39. us USER STATUS statuscode statusmessage INPUT Field Description item value 55 SeQent Real Time Decision Solutions Technical Assistance FAQ Every SeQent product contains a FAQ file specific to that product You can view this FAQ file by visiting the SeQent web site www SeQent com and browse the product page for the product you are using Support Contracts You may purchase a support contract for FirstPAGE based products Various levels of support are available View the SeQent web site www SeQent com and browse the product page for product you are using Help Desk To reach our help desk please use one of the following methods Telephone 1 519 652 0401 Fax 1 519 652 9275 Web www SeQent com Customer Care E Mail support SeQent com Please have your support contract or product license key ready before calling or include it in your correspondence Support is free for product trials and for the first 30 days of product ownership 56 FirstPAGE v9 Protocol Specification Glossary Alias A FirstPAGE Server alias is an alternate name which may be assigned to a destination FirstPAGE Server client applications may choose to allow users to utilize aliases to lookup actual destination names Client A client component utilizes the facilities of a standard NETCON server Typically a GUI application this component provides a user friendly interface of t
40. used to monitor or cancel the request Format PDIST INITIATE distname message Status PDIST STATUS statuscode statusmessage Result PDIST RESULT 1 serialnumber INPUT Item Description distname Personal distribution list name to send message too message Message to send to distribution list OUTPUT Item Description serialnumber Serial number for transaction 34 FirstPAGE v9 Protocol Specification LIST The LIST sub operation facilitates the interrogation of the known personal distribution lists for the currently logged in account Format PDIST LIST Status PDIST STATUS statuscode statusmessage Result PDIST RESULT 0 distlist1 Result PDIST RESULT O distlist2 Result PDIST RESULT 1 distlistN OUTPUT Item Description distlist1 1 personal distribution list name distlist2 2 personal distribution list name distlistN N personal distribution list name REMOVE The REMOVE sub operation facilitates the removal of a personal distribution list within the FirstPAGE Server for the currently logged in user account Format PDIST REMOVE name Status PDIST STATUS statuscode statusmessage INPUT Item Description name Personal distribution list name to remove WRITE The WRITE sub operation facilitates the creation of a new personal distribution list within the FirstPAGE Server for the currently logged in user
Download Pdf Manuals
Related Search