Documentation Project - Fetch SNOW info into Markdown sites via the API
Project name
Documentation Project - Fetch SNOW info into Markdown sites via the APIProject description
This project is cancelled. Reasons discussed and agreed in the Documentation Project meeting of 2020/01/20. Extract here:
Maria proposed, and everyone agreed, to close the student project on SNOW KB conversion to .md files for inserting them in <service>.docs.cern.ch sites. Reasons:
- We can’t oblige service managers to adopt a standard file hierarchy in their documentation sites, so that the KBs’ content could be copied over automatically.
- The main principle of the Web is based on links ==> no content maintenance in >1 places.
Project Description
The CERN IT group on Collaboration, Devices and Applications (CDA) looks, amongst a big amount of the services it provides, into documentation recommendations and tools.
In these discussions, we decided to investigate importing from the CERN Service Portal (Service Now, further referred to as SNOW) the content of Knowledge Base (KB) articles to enhance FAQs of Markdown general documentation. There should be a dedicated sub-section of the documentation, which is often called https://ServiceName.docs.cern.ch. See background info here.
Examples:
The straight forward method is to use OAuth2 tools to authenicate to the SNOW server and obtain the data via the API.
There is also an option to extract info from an Oracle database, where SNOW data are stored. As we are only querying field contents from the Service Catalog, this is an easier option. This method doesn't allow interaction with tickets (reassignment, commenting or resolving), which is fine for our needs.
The database is not updated in real time (though it’s done several times a day, at least every couple of hours). This is not a problem for this project's requirements. A request for such a private DB view was placed mid-November 2019. See it here.
The SNOW team uses this database for reporting (internally and externally) so people don’t query the live platform for this kind of purposes. The SNOW managers would create a database view for us, with a username and a password to query it. This approach requires to be able to connect to this database, which is simpler than the complexity of understanding OAuth technicalities.
Appendix:
Background information with example from a previous effort to extract the values of the short description field of IT CDA services' Service Elements (SEs) (or Functional Elements (FEs) when necessary). See background info here.
The text in the centre of page https://cern.ch/it-dep-cda/services/e-learning should be automatically fetched from SNOW into Jekyll when a SNOW update occurs.
- This is how to request a SNow API https://cern.service-now.com/service-portal/report-ticket.do?name=snow-api-access&se=servicenow-application-support
- The file lcoation of the above example https://gitlab.cern.ch/it-dep-cda/public-website/blob/master/_ic/e-learning.md
- The SNOW content of this service https://cern.service-now.com/service-portal/service-element.do?name=itelearningservice
- SNow expert is Jorge Garcia Cuervo.
- SNow API request example with authentication issues to solve here.
- Manual report extraction method and results here. Doing this is needed to test the validity of data extracted programmatically.
Required skills
Python programming skills for web development. Use and integrate the existing Python library to extract info from SNOW. Experience with authentication/authorisation tools (OAuth2) and REST APIs. Rigorous testing processes. Communication with content owners. Very good level of english understanding, speaking, writing (B2 level).Candidates for this project must be computer programmers. Project can start in the 1st or 2nd quarter 2020. This type of Internship contract offers 1.500 CHF/month. 50% work (2 days per week and 3 days per week the following week) is possible. Contact Maria.Dimou@cern.ch, with CV, recommendation letters and university grades.
Learning experience
Work in a team of skilled programmers and very busy people. This means getting highly competent advice, while also learning to find things on one's own. Learn to present the results in a brief and functional way to the project team and the service owners. Be part of the life of the world's biggest physics laboratory in an IT department with more than 300 experts.Project duration
3 monthsProject area
Data Management Data Analytics LearningContact for further details
Maria DimouReferences
- All documentation-related strategy meetings (most recent first) here.
- A development project on Documentation conversion tools (and more) here.
- An internship project for migrating existing static web sites to markdown here.
- Policy on FAQs May 2019 (requires CERN login - contains links to 2 White Area lectures where the matter eas discussed)
- Preparatory discussion on FAQs February 2019 (requires CERN login)
CERN group
IT-CDA https://cern.ch/it-dep-cda/Status
Cancelled Submitted by Maria Dimou on Wednesday, August 14, 2019 - 11:49.Maria Dimou