There are two types of advisors: blocking and non-blocking advisors. Both types have the ability to enrich the response of a resource with messages. Blocking advisors can only apply to form resources, and will block the form action if messages exist. If a form action is blocked, the action link will not be returned, and attempting to post to the action URI will result in an error message.

The generated source classes corresponding to the defined advisor elements contain the advisor name in the class name. So an <advisor> with the <name>my-resource</name> will be represented in the generated sources by a class named MyResourceAdvisor.

All interfaces defined in the generated template class represent the prototypes which can be implemented. Typically these prototypes will override one method which will return either the rxJava types Observable<Message> or Observable<LinkedMessage>. If an empty Observable is returned, the advisor doesn't have any effect.

Examples on how to do this can be found in the Helix Pattern Catalog. The patterns Advise and Advise-on-read reflect examples of all advisor types.

A example of how to construct a prototype can be found here:

        @Override
        public Observable<LinkedMessage<TermsFormIdentifier>> onLinkedAdvise() {
        if (termsAndConditionsRepository.accepted()) {
        return Observable.empty();
        }
        TermsFormIdentifier termsFormIdentifier = TermsFormIdentifier.builder()
        .withTerms(TermsIdentifier.builder().build())
        .build();
        
        Map<String, String> extras = Collections.singletonMap("some-key", "some-value");
        
        LinkedMessage<TermsFormIdentifier> result = LinkedMessage.<TermsFormIdentifier>builder()
        .withType(StructuredMessageTypes.NEEDINFO)
        .withId("toc-not-accepted")
        .withDebugMessage("You must accept the Terms and Conditions before proceeding with your purchase.")
        .withLinkedIdentifier(termsFormIdentifier)
        .withData(extras)
        .build();
        
        return Observable.just(result);
        }
      

If you want to localize a message, construct an id. Typically, a localized message uses placeholders which can be replaced in the localization process. Data for these placeholders is found in the data field.

If you want to pass more operational or developer-related information in the JSON response, use the debug message field.

The linked identifier is the the identifier of the resource references by the <linked-to> xml element. You might need to inject context information using a Data Injector to construct the linked identifier.

In general, the JSON response's data is a one to one representation of the data provided in the prototype implementation, with two differences. Firstly, the JSON response for for blocking advisors includes the form-submit rel. Secondly, the JSON response for resources with multiple advisors implemented differs based on the advisors implemented.

An example resolvable blocking advisor JSON response:

  {
      "self": {
        "type": "advise.order",
        "uri": "/commerce-legacy/advise/order",
        "href": "http://localhost:8080/advise/order"
    },
    "messages": [
      {
        "type": "needinfo",  
        "id": "toc-not-accepted",
        "debug-message": "You must accept the Terms and Conditions before proceeding with your purchase.",
        "linked-to": {
          "uri": "/commerce-legacy/advise/terms/form",
          "href": "http://localhost:8080/advise/terms/form",
          "type": "advise.terms-form"
        },
        "blocks": {
          "rel": "purchase-action"
        },
        "data": {
          "some-key": "some-value"
        }
      }
    ],
    "links": []
  }
      

An example non-resolvable blocking advisor JSON response:

  {
    "self": {
      "type": "advise.order",
      "uri": "/commerce-legacy/advise/order",
      "href": "http://localhost:8080/advise/order"
    },
    "messages": [
      {
        "type": "error",
        "id": "item.out.of.stock",
        "debug-message": "The camera item is not in stock",
        "data": {
          "item" : "camera"
        },
        "blocks": {
          "rel": "purchase-action"
        }
      }
    ],
    "links": []
  }  
      

An example informational non-blocking advisor JSON response:

  {
    "self": {
      "type": "advise.order",
      "uri": "/commerce-legacy/advise/order",
      "href": "http://localhost:8080/advise/order"
    },
    "messages": [
      {
        "type": "information",
        "id": "purchase.history.information",
        "debug-message": "70 people bought the dress item in the last 2 hours",
        "data": {
          "buyers": "70",
          "item": "dress",
          "time-period": "2"
        }
      }
    ],
    "links": []
  } 
      

An example JSON response for a resource with multiple advisors implemented:

  {
    "self": {
      "type": "advise.order",
      "uri": "/commerce-legacy/advise/order",
      "href": "http://localhost:8080/advise/order"
    },
    "messages": [
      {
        "type": "needinfo",
        "id": "toc-not-accepted",
        "debug-message": "You must accept the Terms and Conditions before proceeding with your purchase.",
        "linked-to": {
          "uri": "/commerce-legacy/advise/terms/form",
          "href": "http://localhost:8080/advise/terms/form",
          "type": "advise.terms-form"
        },
        "data": {
          "some-key": "some-value"
        },
        "blocks": {
          "rel": "purchase-action"
        }
      },
      {
        "type": "information",
        "id": "purchase.history.information",
        "debug-message": "70 people bought the dress item in the last 2 hours",
        "data": {
          "buyers": "70",
          "item": "dress",
          "time-period": "2"
        }
      }
    ],
    "links": []
  }