ECHO has been replaced by the Common Metadata Repository (CMR), a high-performance, high-quality, continuously evolving metadata system that catalogs all data and service metadata records for the EOSDIS system and will be the authoritative management system for all EOSDIS metadata.
The information contained within this ECHO wiki is now archived for historical reference. Please navigate to the CMR wiki pages, or to the CMR Overview page on Earthdata.
The Invocation Service allows ECHO users to request that ECHO invoke an operation on a registered web service implementation enabling the brokering of services. A user specifies the implementation, operation, and parameters to a service, such as Event Notification Service, and ECHO will invoke the requested service.
ECHO tracks the invocations using an Invocation GUID. Requesting an invocation is an asynchronous operation.
The sections below detail current limitations of the invocation service.
Primitive Type Arguments
The Invocation Service can only invoke operations that use primitive types (the basic XML schema primitive types such as "string" and "int").
ECHO returns the results of an invocation as the type "string".
ECHO stores the state of an invocation using the Status Service and the invocation GUID. The following is a list of the states an invocation can enter:
Table 13: Invocation States
The invocation has been accepted by ECHO to be processed.
The invocation has been delayed by the service partner. A status annotation will list the date the invocation has been delayed until.
ECHO is currently validating the invocation request.
ECHO is preparing data to perform the invocation.
ECHO is currently invoking the operation.
The invocation has finished and ECHO is preparing the results of the invocation.
The invocation is complete and the results are available.
The invocation has been aborted due to error. A status annotation will list the details of the error.
This text below lists the operations of the Invocation Service that are specifically intended for end users. Other operations for Service Partners, like
MarkAsynchronous, are detailed in the "Invocation Service Aware Web Services" section on the following page. For more information about Service Partners, refer to the forthcoming ECHO 10.10 Service Partner's Guide.
This operation submits a request to invoke an extended service operation. It is an asynchronous method so it returns an Invocation ID, used to track the progress of the invocation.
The operations and parameters on a web service registered in ECHO can be retrieved using the
GetOperations method on the Extended Services Service. The web service implementation GUID, operation name, and parameters are sent to this operation. The web service implementation GUID must be the GUID of an activated web service implementation registered in ECHO. The operation name is the name of the operation to invoke on the web service. The number and names of the parameters must be correct. The order of the parameters is not important since the names must be unique.
ECHO Path URI Parameters
If you want to use metadata of granules or collections as parameter values when invoking an operation, then you should use ECHO Path URIs. ECHO Path URIs map to the metadata of a granule or collection. If a parameter value is a URI of the correct format, the URI will be resolved and the value retrieved from the metadata will be sent when invoking the web service.
The type retrieved from the metadata must be convertible to the parameter type in the operation; otherwise, the invocation will be aborted. For example if a parameter takes a float and the ECHO Path URI resolves to "ABZ" then invocation will be aborted. See Appendix D, ECHO Path URIs for more information.
Returned Invocation GUID
The return value is an invocation GUID used to track the invocation. The invocation GUID is passed into all the other methods of the Invocation Service to specify the invocation to which the user is referring. As the invocation is processed, the status is set using the Status Service. The Transaction GUID used in the Status Service is the same as the Invocation GUID.
This returns the last state of the invocation and the results if the invocation has completed. The last status will include the current state of the invocation and any annotations to that state. The results will be included if the invocation state is COMPLETE.
Service Partner Operations
Service Partners can create web services that are Invocation Service-aware to gain extra abilities and provide more value to end users when being invoked by ECHO. A service called the Invocation Utility Service enables an Invocation Service-aware web service to delay an invocation, add status information on the invocation, or indicate that the web service is asynchronous.
Invocation Service-aware web services know they are being invoked by ECHO because a special SOAP Header is passed in the SOAP request to invoke the operation. The information passed is the invocation GUID and the URL to the Invocation Utility Service.
SOAP Header Layout
This lists the major elements of the ECHO invocation SOAP header. The namespace of all these elements is http://echo.nasa.gov/echotypes.
Table 14: Invocation SOAP Header Elements
This presence of this tag indicates this is an invocation by ECHO. It holds all of the information.
This contains the invocation GUID that will be used on all the Invocation Utility Service methods.
This contains the URL to the Invocation Utility Service.
SOAP Header Example
This shows an example of what the SOAP header passed during an invocation by ECHO will look like.
<soapenv:Header> <ns1:EchoInvocation soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xmlns:ns1="http://echo.nasa.gov/echoTypes"> <ns1:invocationId soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"> 88A3BDFB-FDA3-4BA6-F3CE-92D052284503 </ns1:invocationId> <ns1:invocationUtilityUrl soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xsi:type="soapenc:string" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"> http://localhost:28000/echo_v8/InvocationUtilityService </ns1:invocationUtilityUrl> </ns1:EchoInvocation> </soapenv:Header>
Invocation Utility Service
The Invocation Utility Service offers methods to Invocation-aware web services.
This operation delays the invocation until the specified date. This is useful if the web service does not currently have the resources available to process the invocation. ECHO will attempt to invoke the web service again at the specified date and time. See the section on Timing Concerns.
This operation allows Invocation aware web services to provide detailed information to end users. The status string passed will be stored in ECHO under the current state of the invocation, which can be retrieved and viewed by users using the Invocation Service or Status Service.
This operation will mark the web service as being asynchronous. ECHO normally assumes when the operation returns that it is complete but if this operation is called, then the invocation state will stay in PERFORMING_INVOCATION until the web service notifies ECHO that it is complete using the Mark Complete operation. See the Timing Concerns section on timing concerns with this operation.
This operation is used by asynchronous web services to notify ECHO that they are complete. The string results of the web service operation are an argument to this operation. Web services calling this method should have previously called the Mark Asynchronous operation.
When a web service being invoked by ECHO returns, ECHO normally assumes the invocation is complete and immediately marks it that way. If a web service wants to delay the invocation or mark it asynchronous, it must call the Delay Invocation and Mark Asynchronous operations before returning from the original invocation.
Invocation Sequence Diagrams
This contains some sequence diagrams showing the steps that happen during a regular and asynchronous invocation.
Normal Invocation Sequence Diagram
This diagram shows the normal sequence of steps when an invocation occurs.
Figure 19: ECHO Invocation Service Sequence
Asynchronous Invocation Sequence Diagram
This diagram shows the sequence of steps when an invocation occurs on an asynchronous web service.
Figure 20: Asynchronous Invocation Sequence