Customer Portal

Get Involved. Join the Conversation.

Topic

    Lord Rob Shorney
    Changelog.yml for custom widgetsAnswered
    Topic posted May 4, 2018 by Lord Rob ShorneyRed Ribbon: 250+ Points 
    82 Views, 4 Comments
    Title:
    Changelog.yml for custom widgets
    Content:

    Hi all,

    Please can someone let me know the structure that the changelog.yml file should be, preferably with an example, I need to be able to display New Features , Api changes, bug fixes, other etc.

    I have trawled the documentation but alas have not found anything

     

    Kind Reagrds

     

    Rob Shorney

    Version:
    Oracle Service Cloud 18A (Build 260 SP 1, CP 322) Framework Version 3.7

    Best Comment

    Willie Eide

    Changelog Format

    Changelogs are stored in YAML format, making them both human-readable, as well as easily parseable.

    Example framework changelog as it would appear on disk

     3.0.2:
       release: "13.2"
       entries:
       - refno: 130124-000011
         changelogID: 123
         description: Added new \'foo\' feature
         level: nano
         category: New Feature
         sortPosition: top
         details:
         - Add this new attribute for extra foo.
         - May need to adjust styling.
     3.0.1:
       release: "12.8"
       entries:
       - refno: 120914-000001
         changelogID: 456
         description: Added new \'bar\' feature
         level: minor
         category: New Feature
         sortPosition: middle
         details:
         - Add this new attribute for extra bar.
       - refno: 120804-000003
         changelogID: 789
         description: Removed some feature
         level: minor
         category: Deprecation
         sortPosition: bottom
         details:
         - We changed this file.
    

    Changelog Entry Fields

    Field Name
    Description
    Field Name
    Description
    ID The automatically generated changelogID. This becomes a unique identifier when paired with the refno.
    Created By The first and last name of the person that created the changelog entry.
    Updated By The first and last name from of the person that last updated the changelog entry.
    Date Created The date and time the entry was created.
    Date Last Updated The date and time the entry was last updated.
    IncidentID The refno of the incident associated with the changelog entry.
    Description A summary of the change that is presented to the customer.
    Level One of 'nano', 'minor' or 'major'. 'nano' indicates no impact to the customer, 'minor' indicates some effort in consuming the change, and 'major' indicates a significant migration effort.
    Category Changelog entries will be grouped by category, one of 'New Feature', 'Bug Fix', 'Api Change' or 'Deprecation'. Defaults to 'Bug Fix'.
    SortPosition Dictates how changelog entries are to be sorted within each category. One of 'top', 'middle', or 'bottom'. Defaults to 'middle'. Changlogs within a category are sorted first by 'SortPosition', then by 'level', then 'date'.
    Targets Either 'framework' or a widget specifier (e.g. input/TextInput) indicating which changelog the entry should be associated with. One per line.
    Details Further information provided to the customer, letting them know the impact of consuming the change, and any tips or instructions necessary. Entries must begin with a hyphen.

     

    Creating a changelog entry using Connect

    Should there arise a need to work with changelogs in an automated fashion, the code below details how this can be done using Connect.

    <?php
    use RightNow\Connect\v1_2 as Connect;
    require_once(get_cfg_var("doc_root") . '/include/ConnectPHP/Connect_init.phph');
    
    function __construct() {
        initConnectAPI();
    }
    
    function _create($data) {
        try {
            $changelog = new Connect\CO\ChangeLogEntry();
            $changelog->IncidentID = Connect\Incident::fetch($data['incidentID']);
            $changelog->Level = Connect\CO\ChangeLogLevel::fetch($data['level']); // nano|minor|major.  Need to lookup ID
            $changelog->Description = $data['description'];
            $changelog->Targets = $data['targets']; // One or many targets, one per line (e.g "framework\ninput/FormInput")
            if ($details = $data['details']) {
                // One or many details, starting with a hyphen (e.g. "- Users will need to replace A with B.\n- The foo attribute is deprecated")
                $changelog->Details = $details;
            }
            if ($category = $data['category']) {
                // New Feature|Bug Fix|Api Change|etc..  Need to lookup ID
                $changelog->Category = Connect\CO\ChangeLogCategory::fetch($category);
            }
            $changelog->save();
        }
        catch (Exception $e) {
            print($e->getMessage());
        }
    }
    

    Comment

     

    • Willie Eide

      I'm looking...

    • Willie Eide

      Changelog Format

      Changelogs are stored in YAML format, making them both human-readable, as well as easily parseable.

      Example framework changelog as it would appear on disk

       3.0.2:
         release: "13.2"
         entries:
         - refno: 130124-000011
           changelogID: 123
           description: Added new \'foo\' feature
           level: nano
           category: New Feature
           sortPosition: top
           details:
           - Add this new attribute for extra foo.
           - May need to adjust styling.
       3.0.1:
         release: "12.8"
         entries:
         - refno: 120914-000001
           changelogID: 456
           description: Added new \'bar\' feature
           level: minor
           category: New Feature
           sortPosition: middle
           details:
           - Add this new attribute for extra bar.
         - refno: 120804-000003
           changelogID: 789
           description: Removed some feature
           level: minor
           category: Deprecation
           sortPosition: bottom
           details:
           - We changed this file.
      

      Changelog Entry Fields

      Field Name
      Description
      Field Name
      Description
      ID The automatically generated changelogID. This becomes a unique identifier when paired with the refno.
      Created By The first and last name of the person that created the changelog entry.
      Updated By The first and last name from of the person that last updated the changelog entry.
      Date Created The date and time the entry was created.
      Date Last Updated The date and time the entry was last updated.
      IncidentID The refno of the incident associated with the changelog entry.
      Description A summary of the change that is presented to the customer.
      Level One of 'nano', 'minor' or 'major'. 'nano' indicates no impact to the customer, 'minor' indicates some effort in consuming the change, and 'major' indicates a significant migration effort.
      Category Changelog entries will be grouped by category, one of 'New Feature', 'Bug Fix', 'Api Change' or 'Deprecation'. Defaults to 'Bug Fix'.
      SortPosition Dictates how changelog entries are to be sorted within each category. One of 'top', 'middle', or 'bottom'. Defaults to 'middle'. Changlogs within a category are sorted first by 'SortPosition', then by 'level', then 'date'.
      Targets Either 'framework' or a widget specifier (e.g. input/TextInput) indicating which changelog the entry should be associated with. One per line.
      Details Further information provided to the customer, letting them know the impact of consuming the change, and any tips or instructions necessary. Entries must begin with a hyphen.

       

      Creating a changelog entry using Connect

      Should there arise a need to work with changelogs in an automated fashion, the code below details how this can be done using Connect.

      <?php
      use RightNow\Connect\v1_2 as Connect;
      require_once(get_cfg_var("doc_root") . '/include/ConnectPHP/Connect_init.phph');
      
      function __construct() {
          initConnectAPI();
      }
      
      function _create($data) {
          try {
              $changelog = new Connect\CO\ChangeLogEntry();
              $changelog->IncidentID = Connect\Incident::fetch($data['incidentID']);
              $changelog->Level = Connect\CO\ChangeLogLevel::fetch($data['level']); // nano|minor|major.  Need to lookup ID
              $changelog->Description = $data['description'];
              $changelog->Targets = $data['targets']; // One or many targets, one per line (e.g "framework\ninput/FormInput")
              if ($details = $data['details']) {
                  // One or many details, starting with a hyphen (e.g. "- Users will need to replace A with B.\n- The foo attribute is deprecated")
                  $changelog->Details = $details;
              }
              if ($category = $data['category']) {
                  // New Feature|Bug Fix|Api Change|etc..  Need to lookup ID
                  $changelog->Category = Connect\CO\ChangeLogCategory::fetch($category);
              }
              $changelog->save();
          }
          catch (Exception $e) {
              print($e->getMessage());
          }
      }
      
    • Lord Rob Shorney

      Hi Willie,

      Thank you so much for this, really helpful, as such a quick response to yes

      Where did you find the information/ I trawled all the documentation and couldn't find anything.

      Kind Regards
      Rob Shorney

    • Willie Eide

      Internal stash. I didn't see anything proprietary in there, so I may consider publishing this publicly. 
      No one really has queried for this information which is why it was kept internally.