{"id":8435,"date":"2022-02-07T14:28:00","date_gmt":"2022-02-07T22:28:00","guid":{"rendered":"https:\/\/minisoft.com\/support\/?p=8435"},"modified":"2022-06-08T15:48:51","modified_gmt":"2022-06-08T22:48:51","slug":"eformz-api-management-developer-resources","status":"publish","type":"post","link":"https:\/\/c002.minisoft.com\/support\/eformz-api-management-developer-resources\/","title":{"rendered":"eFORMz API Management (Developer Resources) [Web Services]"},"content":{"rendered":"\n

NOTE: For information on the Ship\/FX API, consult the following: Ship\/FX API Management (Developer Resources)<\/a><\/p>\n\n\n\n

\"\"<\/figure>\n\n\n\n

Drop Ship<\/h1>\n\n\n\n

Calling the eFORMz dropship template library makes use of the ‘output’ endpoint, which is described in more detail below. <\/p>\n\n\n\n

Dropship Standardized XML Schema: DropShipSchema<\/a><\/p>\n\n\n\n

Call Dropship (JSON): DropShipSample<\/a><\/p>\n\n\n\n

\"\"<\/a><\/figure>\n\n\n\n

Endpoints: Director\/Output<\/h1>\n\n\n\n

There are two primary endpoints available to eFORMz customers. These are the \u2018director\u2019 and \u2018output\u2019 endpoints.<\/p>\n\n\n\n

An \u201cendpoint\u201d is one end of a communication channel. When an API interacts with another system<\/a>, the touchpoints of this communication are considered endpoints. For APIs, an endpoint can include a URL of a server or service. The place that APIs send requests and where the resource lives is called an endpoint.<\/p>\n\n\n\n

The \u2018director\u2019 endpoint returns success or failure only. It processes data in the background. The \u2018output\u2019 endpoint processes data during the call and returns the results as part of the web service call. Both of these endpoints can take parameters either through the URL or in the data.<\/p>\n\n\n\n

While the portion of the URL with authentication is encrypted for transmission, many people have policies restricting this practice. Passing the parameters in the data, including authentication, is possible using either XML or JSON. The order or sequence of elements in either format is not relevant to the processing.<\/p>\n\n\n\n

eFORMz Web Service API response codes<\/h3>\n\n\n\n

As stated above, for an API call to the \u201cdirector\u201d endpoint, there are the two responses: success or failure. Effectively, you are pushing data into an \u2018-ac\u2019 (accessible) Local Director Queue. The response codes are 200<\/code> for success and 500<\/code> for an error.<\/p>\n\n\n\n

The \u2018output\u2019 endpoint executes a project, which can call other projects, and returns output. The type of project output is configurable. There are quite a few responses possible if the URL is not formed in an expected fashion. A good source for the \u2018types\u2019 of endpoints is the AuthenticationCfg.xml file. There you will find:
\u2022 <Authentication Name=”activeFORMz”
\u2022 <Authentication Name=”eFORMz Web Services”
\u2022 <Authentication Name=”ServiceManagerManagement”
\u2022 <Authentication Name=”ServiceManagerConfiguration”<\/p>\n\n\n\n

The AuthenticationCfg.xml has 401<\/code> responses in addition to the 200<\/code> and 500<\/code> codes.<\/p>\n\n\n\n

Authentication\/Authorization<\/h2>\n\n\n\n

Authentication proves who you are. Authorization refers to what you are allowed to see and do. AuthenticationCfg.xml<\/code> is the file that handles authentication and authorization. Web Service Authentication can be through username\/password, LDAP, Kerberos or Azure AD. <\/p>\n\n\n\n

Basic (username:password<\/code>)
Authenticator=\"com.minisoft.common.CredentialsInXMLFileAuthenticator\"<\/code>
Authenticator=\"com.minisoft.common.ADAuthenticator\"
<\/code>Authenticator=\"com.minisoft.common.LDAPAuthenticator\"<\/code><\/p>\n\n\n\n

Bearer (Token-based authentication)
Authenticator=\"com.minisoft.common.AADAuthenticator\"<\/code><\/p>\n\n\n\n

The on-premises Microsoft Active Directory is accessed through Kerberos. Azure Active Directory is web-based and has its own definition within the AuthenticationCfg.xml<\/code>. Web Service Authorization (for an authenticated user) is through the URL\/URI used. This depends on the endpoint used and can be the project of config parameters. For example:<\/p>\n\n\n\n

<Group Name=\"Testing\">\n     <Member Name=\"projects\/eSHIP\/SHIPFXConfiguration.xml\" \/>\n     <Member Name=\"projects\/SHIPFX\/SHIPFXAdmin.xml\" \/>\n     <Member Name=\"projects\/eSHIP\/ShipperWS.efz\" \/>\n     <Member Name=\"projects\/eSHIP\/GetRatesWS.efz\" \/>\n<\/Group><\/code><\/pre>\n\n\n\n
URL Formats<\/h2>\n\n\n\n
eFORMz API: URL Formats<\/a><\/p>\n\n\n\n
Parameters<\/h2>\n\n\n\n
eFORMz API URL Parameters<\/a><\/p>\n\n\n\n
Director Sample<\/h2>\n\n\n\n
URL<\/h3>\n\n\n\n
http:\/\/localhost:8001\/servlet\/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp<\/pre>\n\n\n\n
XML<\/h3>\n\n\n\n
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<ServiceConfiguration ServiceType=\"director\" Host=\"localhost\" Port=\"9996\" ConfigurationName=\"accessible.cfg\" QueueName=\"Accessible\" NameTemplate=\"data_.xml\" ProcessData=\"true\" UseParmsAsData=\"false\">\n  <InputData usepostdata=\"false\" format=\"XML\" encoding=\"none\">\n    <Data>\n      <AdditionalInfo>\n                <misc>info<\/misc>\n      <\/AdditionalInfo>\n    <\/Data>\n  <\/InputData>\n<\/ServiceConfiguration>\n<\/code><\/pre>\n\n\n\n
JSON<\/h3>\n\n\n\n
{\n    \"ServiceConfiguration\":\n          {\n             \"ServiceType\":\"director\",\n             \"Port\":9996,\n             \"NameTemplate\":\"data_.json\",\n             \"Host\":\"localhost\",\n             \"UseParmsAsData\":false,\n             \"ConfigurationName\":\"accessible.cfg\",\n             \"InputData\":\n             {\n                    \"usepostdata\":false,\n                    \"format\":\"JSON\",\n                    \"Data\":\n                    {\n                          \"AdditionalInfo\":\n                               {\n                               \u201cmisc\u201d:\u201dinfo\u201d\n                               },\n                    },\n                    \"encoding\":\"none\"\n             },\n             \"QueueName\":\"Accessible\",\n             \"ProcessData\":true\n          }\n}<\/code><\/pre>\n\n\n\n
Output Sample<\/h2>\n\n\n\n
XML<\/h3>\n\n\n\n
http:\/\/localhost:8001\/servlet\/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&config=projects\/OutputGuideServer\/configOutputUsePostData.xml<\/pre>\n\n\n\n
<?xml version=\"1.0\" encoding=\"utf-8\"?> \n<ServiceConfiguration ServiceType=\"output\" project=\"projects\/OutputGuideServer\/MapPackSlipData0.efz\" format=\".xml\"> \n  <InputData format=\"XML\"> \n    <Root> \n      <abc>test<\/abc> \n    <\/Root> \n  <\/InputData> \n<\/ServiceConfiguration> <\/code><\/pre>\n\n\n\n
The root node must be named ServiceConfiguration<\/code> and the parameters are specified as attributes of that node. The output<\/code> parameter directs the eFORMz web service to return the output of an eFORMz project specified by the project<\/code> parameter. The calling application can pass in input data for the project in a variety of ways. The InputData<\/code> node with the attribute format<\/code> specifies the format of the embedded data. The data passed to the project is the Root<\/code> node and all of its descendant nodes (abc<\/code> in this example).<\/p>\n\n\n\n
JSON<\/h3>\n\n\n\n
\"\"<\/a>
JSONTest.postman_collection.json<\/figcaption><\/figure>\n\n\n\n
http:\/\/localhost:8001\/servlet\/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&output&project=projects\/JSON\/MirrorTest.efz&usepostdata&dataformat=JSON&format=.txt<\/pre>\n\n\n\n
{\n    \"success\": true,\n    \"header\": null,\n    \"data\": {\n        \"Messages\": null,\n        \"FulfillmentAddress\": [\n            {\n                \"AddressTypeId\": {\n                    \"AddressTypeId\": \"Billing\"\n                },\n                \"Address\": {\n                    \"FirstName\": \"First\",\n                    \"LastName\": \"Last\",\n                    \"Address1\": \"1024 First Street\",\n                    \"Address2\": \"Suite 311\",\n                    \"Address3\": null,\n                    \"City\": \"Snohomish\",\n                    \"State\": \"WA\",\n                    \"PostalCode\": \"98290\",\n                    \"County\": null,\n                    \"Country\": \"US\",\n                    \"Phone\": \"8006820200\",\n                    \"Email\": \"sales@minisoft.com\"\n                },\n                \"Process\": null\n            },\n        ],\n    },\n    \"message\": null,\n    \"errors\": [],\n    \"exceptions\": [],\n    \"messages\": {\n        \"Message\": [],\n        \"Size\": 0\n    },\n}<\/code><\/pre>\n\n\n\n
Download the working sample with a Postman test call here: JSONTest<\/strong><\/a>. JSON comes in, the MirrorAction.efz project affects the fields and JSON is sent out.<\/p>\n\n\n\n
Set Response Header<\/h3>\n\n\n\n
Response headers can be set by the project defining and setting global variables:<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
Source Parameter (Create JSON)<\/h3>\n\n\n\n
&Source<\/code> is an API parameter<\/a> used to to identify a Global Variable in the called project.<\/p>\n\n\n\n
http://localhost:8001\/servlet\/com.minisoft.AppServer.AppServer?APP=com.minisoft.eformz.eFORMzApp&output&project=projects\/sample\/JSON_IO.efz&usepostdata=true&source=gsource<\/code><\/pre>\n\n\n\n
When the variable is found in the set of Global Variables having the \u201cPass last value to Queue Monitor\u201d set, the last value is returned as the API call return data.<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
Tag: Make an API call<\/p>\n","protected":false},"excerpt":{"rendered":"
NOTE: For information on the Ship\/FX API, consult the following: Ship\/FX API Management (Developer Resources) Drop Ship Calling the eFORMz dropship template library makes use of the ‘output’ endpoint, which is described in more detail below. Dropship Standardized XML Schema: DropShipSchema Call Dropship (JSON): DropShipSample Endpoints: Director\/Output There are two primary endpoints available to eFORMz […]<\/p>\n","protected":false},"author":75,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[454],"tags":[584,583,633,342,25],"_links":{"self":[{"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/posts\/8435"}],"collection":[{"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/users\/75"}],"replies":[{"embeddable":true,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/comments?post=8435"}],"version-history":[{"count":26,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/posts\/8435\/revisions"}],"predecessor-version":[{"id":10367,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/posts\/8435\/revisions\/10367"}],"wp:attachment":[{"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/media?parent=8435"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/categories?post=8435"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/c002.minisoft.com\/support\/wp-json\/wp\/v2\/tags?post=8435"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}