Transcription
Altair Monarch v2020.0MONARCH SERVERCONTENT API GUIDE
TABLE OF CONTENTSIntroduction . 1Principle and purpose . 1Available operations . 1API testing . 1Working with the Monarch Server API . 2Request authentication . 2API entry point. 2Response type and error handling . 2Monarch Server API Usage Sample . 3API reference . 4Login . 4Logging in . 4Autologin . 4Logging out . 5SummaryExport . 6Export to PDF . 6Export to XLS. 8Export raw data (XML) . 9Export — HTML View . 13ReportExport . 16Export to PDF . 16Export raw data (XML) . 17Export to PRF . 19Export — HTML View . 21Export to ES Style . 22Model . 24GET method . 24Report . 25GET method . 25POST method . 31Search. 37Search by criteria . 37Saved search . 45Saved search list . 50TableExport . 56Export to PDF . 56Export to XLS. 58Export raw data (XML) . 61
Export — HTML View . 65Export to ES Style . 68Dynamic Login . 71Altair Engineering, Inc. All Rights Reserved. / Nasdaq:ALTR / altair.com
INTRODUCTIONMonarch Server (MS) provides the API for external applications based on the HTTP protocol.PRINCIPLE AND PURPOSEThe API allows external applications to use various functions of MS and access the MS database data. Using theAPI, a new front-end or automation application can be built easily on top of MS.AVAILABLE OPERATIONSThe API’s functionality consists of the following major parts: Access to the MS Database data includes retrieving various database data such as saved search lists anddocument type information. Results are represented in a defined XML or JSON format. Document search includes performing document searches over the MS database. Both pre-defined savedsearches and arbitrary criteria-based searches can be performed. The result is a list of found documents in theXML or JSON format. Report data retrieval. Report data can be taken from the MS storage in a plain text format. Access to data-derived views. Most of the data-derived views available in the MS system can be accessed thisway. This includes report and table/summary data exported into various presentational formats, such as XML,JSON, HTML, Excel, PRF, PDF, and ES Style. The format of output data depends on the particular view type.API TESTINGYou can test how the API works on the interactive API help page located here:http://localhost/MSClient/api/helpYou can view detailed information about each method on the method’s page. You can then test it by clicking the TestAPI button.NOTESIn Monarch Server v2020.0 that is upgraded from previous versions (e.g., v13.2), thevirtual folders could still be labeled as “DSClient” (or "DSAdmin"). In this case, use“DSClient” (or "DSAdmin”) instead of “MSClient” (or “MSAdmin”) to open the Client (orAdmin) page.Monarch Server v2020.0 Content API Guide1
WORKING WITH THE MONARCHSERVER APITo work with the Monarch Server API successfully, review the information below.REQUEST AUTHENTICATIONFor authentication, use the Login method.API ENTRY POINTAccess to the MS HTTP API is performed through an entry point.The format of the request URL ishttp:// host : port /MSClient/apiHere, host is the name of the computer where MS is running, and port is the port number on which MS islistening.The request can be sent using either an HTTP GET or an HTTP POST method (unless specified otherwise). Thetarget area can be either the top window or a new browser window.Parameter values that contain URL-prohibited symbols must be encoded as required by the URL specification.Some parameters depend on the particular operation type.For example, the list of all saved searches can be retrieved with the following request (assuming that the built-inadministrator account is SE TYPE AND ERROR HANDLINGThe response to a request can be one of the following depending on the success condition: Request succeeded. The response has a corresponding MIME-type or an HTTP redirect. Request failed.Depending on the operation nature and status, the response can be one of the following: The standard MS error page describing the nature of the error (for HTML-based views) HTTP error code with an optional message XML error description (non-HTML views)In case of an XML error description, the response type is text/xml. The format of an XML error message isMonarch Server v2020.0 Content API Guide2
Error Message [Message] /Message ExceptionMessage [ExceptionMessage] /ExceptionMessage ExceptionType [ExceptionType] /ExceptionType StackTrace [StackTrace] /StackTrace /Error The client application can check the root node’s name if text/xml content is returned to determine whether an erroroccurred.MONARCH SERVER API USAGE SAMPLEUse the Login method for user Upon logging in, the user can either stay in the system or leave via the Logout ctUrl {redirectUrl}The user can use different methods for data viewing; for example, the user can retrieve a table export in PDF formatby using the following API method.1.Use the Saved search list method to get the Search ID.http://localhost/MSClient/api/searches/2.Then, use the Saved search method with the Search ID value to get the Document IDs.http://localhost/MSClient /api/search/{searchid}3.Use the Model method with the Document ID value to get the Model ID used with the current document type andto get the data on the current model (e.g., filters, sorting, and tModel?documentId {documentId}4.Finally, use the TableExport — Export to PDF method and supply the model values to get a filtered and sortedPDF export ntIds}/table/pdf?sortName {sortName}&filterName {filterName}&modelName {modelName}&joinPassword {joinPassword}Monarch Server v2020.0 Content API Guide3
API REFERENCEThe following is a complete reference of methods supported by the MS API.LOGINUse the following methods to begin and end a user session to work with MS.Logging inUsed to establish a “session” — a secure environment for further operation.POST methodThe entry point for this method isapi/loginRequest InformationURI Parameters: none.Body ingNoneDomainUser domainStringNoneRequest format sample (application/xml, text/xml) LoginRequest xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" Username admin /Username Password password /Password /LoginRequest AutologinUsed to establish a “session” when the Active directory authentication is enabled with the selected SSO option.Monarch Server v2020.0 Content API Guide4
POST methodThe entry point for this method isapi/autologinRequest InformationURI Parameters: none.Body Parameters: none.Logging outThis operation terminates the current API session. It can be useful when the maximum number of user sessions islimited.GET methodThe entry point for this method isapi/logout?redirectUrl {redirectUrl}Request InformationURI Parameters:NameDescriptionTypeAdditional informationredirectUrlURL for the redirect after sessiontermination. If this parameter is absent,then no redirect is sent.StringNoneBody Parameters: none.Monarch Server v2020.0 Content API Guide5
SUMMARY EXPORTSummary information can be exported into a variety of formats listed below.Export to PDFAdobe Portable Document Format can represent report data, tables, and summaries. You can export summary datausing both GET and POST methods.GET methodThe entry point for this method df?filterName {filterName}&modelName {modelName}Request InformationURI Parameters:NameDescriptionTypeAdditional informationdocumentIdsComma-separated list of IDs of thedocuments to retrieve. All of thesedocuments must be of the same type. Ifthe documents requested are of morethan one type, an error is returned.StringRequiredsummaryNameThe name of a summary that is usedfor summary generation.StringRequiredfilterNameName of the filter used for table orsummary generation. The filterspecified must exist in a report modelset for this document type; otherwise,an error is returned.StringNonemodelNameName of the model to be used forexport. If this parameter is absent, thenthe appropriate model is detected out ofthe document IDs passed (however,this method is slow).StringNoneBody Parameters: none.Response InformationThe response MIME-type isapplication/pdfPOST methodThe entry point for this method isapi/export/summary/pdfMonarch Server v2020.0 Content API Guide6
Request InformationURI Parameters: none.Body nFilterNameName of the filter to be used for table orsummary generation. The specified filter mustexist in the report model set for this documenttype; otherwise, an error is returned.StringNoneSummaryNameThe name of a summary that is used forsummary generation.StringRequiredModelNameName of the model to be used for export. If thisparameter is absent, then the appropriate modelis detected out of the document IDs passed(however, this method is slow).StringNoneDocumentIdsList of IDs of the documents to retrieve. All ofthese documents must be of the same type. Ifthe documents requested are of more than onetype, an error is returned.Collection ofintegersRequired minlength: 1Request format sample (application/json, text/json){"FilterName": "sample string 1","SummaryName": "sample string 2","ModelName": "sample string 3","DocumentIds": [1,2]}Request format sample (application/xml, text/xml) SummaryExportRequest xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" DocumentIds int 1 /int int 2 /int /DocumentIds FilterName sample string 1 /FilterName SummaryName sample string 2 /SummaryName ModelName sample string 3 /ModelName /SummaryExportRequest Response InformationThe response MIME-type isapplication/pdfMonarch Server v2020.0 Content API Guide7
Export to XLSThe Excel format is suitable for displaying tables and summaries.GET methodThe entry point for this method ls?filterName {filterName}&modelName {modelName}Request InformationURI Parameters:NameDescriptionTypeAdditional informationdocumentIdsComma-separated list of IDs of documentsto retrieve. All of these documents must beof the same type. If the documentsrequested are of more than one type, anerror is returned.StringRequiredsummaryNameThe name of the summary that is used forsummary generation.StringRequiredfilterNameName of the filter used for table or summarygeneration. The specified filter must exist inthe report model set for this document type;otherwise, an error is returned.StringNonemodelNameName of the model to be used for export. Ifthis parameter is absent, then theappropriate model is detected out of thedocument IDs passed (however, this methodis slow).StringNoneBody Parameters: none.Response InformationThe response MIME-type isapplication/vnd.ms-excelPOST methodThe entry point for this method isapi/export/summary/xlsRequest InformationURI Parameters: none.Body Parameters:Monarch Server v2020.0 Content API Guide8
NameDescriptionTypeAdditional informationFilterNameName of the filter used for table orsummary generation. The specified filtermust exist in the report model set for thisdocument type; otherwise, an error isreturned.StringNoneSummaryNameThe name of the summary that is used forsummary generation.StringRequiredModelNameName of the model to be used for export. Ifthis parameter is absent, then theappropriate model is detected out of thedocument IDs passed (however, thismethod is slow).StringNoneDocumentIdsList of IDs of the documents to retrieve. Allof these documents must be of the sametype. If the documents requested are ofmore than one type, an error is returned.Collection ofintegersRequired min length: 1Request format sample (application/json, text/json){"FilterName": "sample string 1","SummaryName": "sample string 2","ModelName": "sample string 3","DocumentIds": [1,2]}Request format sample (application/xml, text/xml) SummaryExportRequest xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" DocumentIds int 1 /int int 2 /int /DocumentIds FilterName sample string 1 /FilterName SummaryName sample string 2 /SummaryName ModelName sample string 3 /ModelName /SummaryExportRequest Response InformationThe response MIME-type isapplication/vnd.ms-excelExport raw data (XML)This method is used to export raw summary data (in XML format).Monarch Server v2020.0 Content API Guide9
GET methodThe entry point for this method ilterName {filterName}&modelName {modelName}Request InformationURI ndocumentIdsList of IDs of the documents toretrieve. All of these documents mustbe of the same type. If the documentsrequested are of more than one type,an error is returned.StringRequiredsummaryNameThe name of the summary that isused for summary generation.StringRequiredfilterNameName of the filter used for table orsummary generation. The specifiedfilter must exist in the report modelset for this document type; otherwise,an error is returned.StringNonemodelNameName of the model to be used forexport. If this parameter is absent,then the appropriate model isdetected out of the document IDspassed (however, this method isslow).StringNoneBody Parameters: none.Response InformationResource ditional informationHeadersIncludes all column headersin this table.Collection of HeaderNoneRowsIncludes all table data.Collectionof RowDataNoneResponse formats (application/xml, text/xml) XmlExportResponse xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" Monarch Server v2020.0 Content API Guide10
Headers Header Name sample string 1 /Name FieldType String /FieldType /Header Header Name sample string 1 /Name FieldType String /FieldType /Header /Headers Rows RowData Values string sample string 1 /string string sample string 2 /string /Values /RowData RowData Values string sample string 1 /string string sample string 2 /string /Values /RowData /Rows /XmlExportResponse POST methodThe entry point for this method isapi/export/summaryRequest InformationURI Parameters: none.Body nFilterNameName of the filter used for table or summarygeneration. The specified filter must exist in thereport model set for this document type;otherwise, an error is returned.StringNoneSummaryNameThe name of the summary that is used forsummary generation.StringRequiredModelNameName of the model to be used for export. If thisparameter is absent, then the appropriate modelis detected out of the document IDs passed(however, this method is slow).StringNoneDocumentIdsList of IDs of the documents to retrieve. All ofthese documents must be of the same type. IfCollection of integersRequired minlength: 1Monarch Server v2020.0 Content API Guide11
NameDescriptionAdditionalinformationTypethe documents requested are of more than onetype, an error is returned.Request format sample (application/json, text/json){"FilterName": "sample string 1","SummaryName": "sample string 2","ModelName": "sample string 3","DocumentIds": [1,2]}Request format sample (application/xml, text/xml) SummaryExportRequest xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" DocumentIds int 1 /int int 2 /int /DocumentIds FilterName sample string 1 /FilterName SummaryName sample string 2 /SummaryName ModelName sample string 3 /ModelName /SummaryExportRequest Response InformationResource ditional informationHeadersIncludes all column headers in this table.Collection of HeaderNoneRowsIncludes all table data.Collection of RowDataNoneResponse format sample (application/xml, text/xml) XmlExportResponse xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" Headers Header Name sample string 1 /Name FieldType String /FieldType /Header Header Name sample string 1 /Name FieldType String /FieldType /Header Monarch Server v2020.0 Content API Guide12
/Headers Rows RowData Values string sample string sample /Values /RowData RowData Values string sample string sample /Values /RowData /Rows /XmlExportResponse string 1 /string string 2 /string string 1 /string string 2 /string Export — HTML ViewThe HTML format can represent report data, tables, and summaries. You can export summary data using both GETand POST methods.GET methodThe entry point for this method tml/{pageNum}?filterName {filterName}&modelName {modelName}Request InformationURI Parameters:NameDescriptionTypeAdditional informationdocumentIdsList of IDs of the documents toretrieve. All of these documentsmust be of the same type. If thedocuments requested are of morethan one type, an error is returned.StringRequiredsummaryNameThe name of the summary that isused for summary generation.StringRequiredfilterNameName of the filter used for table orsummary generation. The specifiedfilter must exist in the report modelset for this document type;otherwise, an error is returned.StringNonemodelNameName of the model to be used forexport. If this parameter is absent,then the appropriate model isdetected out of the document IDspassed (however, this method isStringNoneMonarch Server v2020.0 Content API Guide13
NameDescriptionTypeAdditional informationIntegerNoneslow).pageNumNumber of pages to return. Validrange is from 1 to the number ofpages.Body Parameters: none.Response InformationThe response MIME-type istext/htmlPOST methodThe entry point for this method isapi/export/summary/htmlRequest InformationURI Parameters: none.Body ePageNumNumber of pages to return. Valid range is from 1to the number of pages.IntegerRange: inclusivebetween 1 and2147483647FilterNameName of the filter used for table or summarygeneration. The specified filter must exist in thereport model set for this document type;otherwise, an error is returned.StringNoneSummaryNameThe name of the summary that is used forsummary generation.StringRequiredModelNameName of the model to be used for export. If thisparameter is absent, then the appropriate modelis detected out of the document IDs passed(however, this method is slow).StringNoneDocumentIdsList of IDs of the documents to retrieve. All ofthese documents must be of the same type. Ifthe documents requested are of more than onetype, an error is returned.Collection ofintegersRequired min length:1Request format sample (application/json, text/json)Monarch Server v2020.0 Content API Guide14
{"PageNum": 1,"FilterName": "sample string 1","SummaryName": "sample string 2","ModelName": "sample string 3","DocumentIds": [1,2]}Request format sample (application/xml, text/xml) HtmlSummaryExportRequest xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" DocumentIds int 1 /int int 2 /int /DocumentIds FilterName sample string 1 /FilterName SummaryName sample string 2 /SummaryName ModelName sample string 3 /ModelName PageNum 1 /PageNum /HtmlSummaryExportRequest Response InformationThe response MIME-type istext/htmlMonarch Server v2020.0 Content API Guide15
REPORT EXPORTReport information can be exported into a variety of formats listed below.Export to PDFAdobe Portable Document Format can represent report data, tables, and summaries.GET methodThe entry point for this method isapi/export/{documentIds}/report/pdfRequest InformationURI ndocumentIdsComma-separated List of IDs of thedocuments to retrieve. All of thesedocuments must be of the same type. Ifthe documents requested are of more thanone type, an error is returned.StringRequiredBody Parameters: none.Response InformationThe response MIME-type isapplication/pdfPOST methodThe entry point for this method isapi/export/report/pdfRequest InformationURI Parameters: none.Body Parameters:NameDescriptionTypeDocumentIdsList of IDs of the documents to retrieve.All of these documents must be of thesame type. If the documents requestedare of more than one type, an error isreturned.Collection of integersAdditionalinformationRequired minlength: 1Request format sample (application/json, text/json){Monarch Server v2020.0 Content API Guide16
"DocumentIds": [1,2]}Request format sample (application/xml, text/xml) ReportExportRequest xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" DocumentIds int 1 /int int 2 /int /DocumentIds /ReportExportRequest Response InformationThe response MIME-type isapplication/pdfExport raw data (XML)This method is used to export raw report data (in the XML format).GET methodThe entry point for this method isapi/export/{documentIds}/reportRequest InformationURI Parameters:NameDescriptionTypeAdditional informationdocumentIdsComma-separated list of IDs of the documents toretrieve. All of these documents must be of thesame type. If the documents requested are of morethan one type, an error is returned.StringRequiredBody Parameters: none.Response InformationResource TypeAdditionalinformationPagesResponseReport pagesCollection of PageResponseNoneResponse format sample (application/xml, text/xml)Monarch Server v2020.0 Content API Guide17
XmlReportExportResponse xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" PagesResponse PageResponse Lines string sample string 1 /string string sample string 2 /string /Lines /PageResponse PageResponse Lines string sample string 1 /string string sample string 2 /string /Lines /PageResponse /PagesResponse /XmlReportExportResponse POST methodThe entry point for this method isapi/export/reportRequest InformationURI Parameters: none.Body Parameters:NameDescriptionTypeDocumentIdsList of IDs of the documents to retrieve.All of these documents must be of thesame type. If the documents requestedare of more than one type, an error isreturned.Collection of integersAdditionalinformationRequired min length:1Request format sample (application/json, text/json){"DocumentIds": [1,2]}Request format sample (application/xml, text/xml) ReportExportRequest xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" DocumentIds int 1 /int int 2 /int /DocumentIds /ReportExportRequest Response InformationMonarch Server v2020.0 Content API Guide18
Resource TypeAdditional informationPagesResponseReport's pagesCollectionof PageResponseNoneResponse format sample (application/xml, text/xml) XmlReportExportResponse xmlns:xsd "http://www.w3.org/2001/XMLSchema"xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" PagesResponse PageResponse Lines string sample string 1 /string string sample string 2 /string /Lines /PageResponse PageResponse Lines string sample string 1 /string string sample string 2 /string /Lines /PageResponse /PagesResponse /XmlReportExportResponse Export to PRFA portable report format can present report data in conjunction with data model/navigational information.GET methodThe entry point for this method delName {modelName}Request InformationURI ndocumentIdsComma-separated list of IDs of thedocuments to retrieve. All of these documentsmust be of the same type. If the documentsrequested are of more than one type, an erroris returned.StringRequiredmodelNameName of the model to be used for export. Ifthis parameter is absent, then the appropriatemodel is detected out of the document IDsStringNoneMonarch Server v2020.0 Content API Guide19
NameDescriptionTypeAdditionalinformationpassed (however, this method is slow).Body Parameters: none.Response InformationThe response MIME-type isapplication/prfPOST methodThe entry point for this method isapi/export/report/prfRequest InformationURI Parameters: none.Body nModelNameName of the model to be used for export. Ifthis parameter
Monarch Server v2020.0 Content API Guide 1 INTRODUCTION Monarch Server (MS) provides the API for external applications based on the HTTP protocol. PRINCIPLE AND PURPOSE The API allows external applications to use various functions of MS and access the MS database data. Using the API, a new front-end or automation application can be built easily .
