paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 36 Packages Projects Releases Wiki Activity

updating the pr on the feedback to add docs, remove some items not needed including the preview html

Browse Source 
Signed-off-by: Joe Patterson <jrwpatterson@gmail.com>
This commit is contained in:
Joe Patterson
2022-10-17 11:02:15 +10:00
parent bc825a7a7b
commit d7b0a11768
13 changed files with 302 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/software-catalog/external-integrations.md
+126
View File
@@ -261,6 +261,132 @@ the `connect` call has been made to the provider.
Start up the backend - it should now start reading from the previously
registered location and you'll see your entities start to appear in Backstage.
### Example User Entity Provider
If you have a 3rd party entity provider such as an internal HR system that you wish to use you are not limited to using our entity providers, (or simply wish to add to existing entity providers with your own data).
We can create an entity provider to read entities that are based off that provider.
We create a basic entity provider as shown above. In the example below we might want to extract our users from an HR system, I am assuming the HR system already has the slackUserId to get that information please see the [Slack Api](https://api.slack.com/methods).
```typescript
import {
ANNOTATION_LOCATION,
ANNOTATION_ORIGIN_LOCATION,
} from '@backstage/catalog-model'
import {
EntityProvider,
EntityProviderConnection,
} from '@backstage/plugin-catalog-backend'
import { WebClient } from '@slack/web-api'
import {kebabCase} from 'lodash'
interface Staff {
displayName: string
slackUserId: string
jobTitle: string
photoUrl: string
address: string
email:string
}
export class UserEntityProvider implements EntityProvider {
private readonly getStaffUrl: string
protected readonly slackTeam: string
protected readonly slackToken: string
protected connection?: EntityProviderConnection
static fromConfig(config: Config, options: { logger: Logger }) {
const getStaffUrl = config.getString('staff.url')
const slackToken = config.getString('slack.token')
const slackTeam = config.getString('slack.team')
return new UserEntityProvider({
...options,
getStaffUrl,
slackToken,
slackTeam,
})
}
private constructor(options: {
getStaffUrl: string
slackToken: string
slackTeam: string
}) {
this.getStaffUrl = options.getStaffUrl
this.slackToken = options.slackToken
this.slackTeam = options.slackTeam
}
async getAllStaff(): Promise<Staff>{
await return axios.get(this.getStaffUrl)
}
public async connect(connection: EntityProviderConnection): Promise<void> {
this.connection = connection
}
async run(): Promise<void> {
if (!this.connection) {
throw new Error('USer Connection Not initialized')
}
const userResources: UserEntity[] = []
const staff = await this.getAllStaff()
for (const user of staff) {
// we can add any links here in this case it would be adding a slack link to the users so you can directly slack them.
const links =
user.slackUserId != null && user.slackUserId.length > 0
? [
{
url: `slack://user?team=${this.slackTeam}&id=${user.slackUserId}`,
title: 'Slack',
icon: 'message',
},
]
: undefined
const userEntity: UserEntity = {
kind: 'User',
apiVersion: 'backstage.io/v1alpha1',
metadata: {
annotations: {
[ANNOTATION_LOCATION]: 'hr-user-https://www.hrurl.com/',
[ANNOTATION_ORIGIN_LOCATION]: 'hr-user-https://www.hrurl.com/',
},
links,
// name of the entity
name: kebabCase(user.displayName as string),
// name for display purposes could be anything including email
title: user.displayName as string,
},
spec: {
profile: {
displayName: user.displayName as string,
email: user.email,
picture: user.photoUrl ?? 'fake',
// we can add any string/string here and it will be displayed on a user profile card, eg Job Title, Address, or any other information you want displayed
'Job Title': user.jobTitle as string,
'Address': user.address,
},
memberOf: [],
},
}
userResources.push(userEntity)
}
await this.connection.applyMutation({
type: 'full',
entities: userResources.map((entity) => ({
entity,
locationKey: 'hr-user-https://www.hrurl.com/',
})),
})
}
```
## Custom Processors
The other possible way of ingesting data into the catalog is through the use of
packages/catalog-model/api-report.md
+14 -5
View File
@@ -269,6 +269,13 @@ export { GroupEntityV1alpha1 };
// @public
export const groupEntityV1alpha1Validator: KindValidator;
// @public
export type GroupProfile = Record<string, string> & {
displayName?: string;
email?: string;
picture?: string;
};
// @public (undocumented)
export function isApiEntity(entity: Entity): entity is ApiEntityV1alpha1;
@@ -497,6 +504,13 @@ export { UserEntityV1alpha1 };
// @public
export const userEntityV1alpha1Validator: KindValidator;
// @public
export type UserProfile = Record<string, string> & {
displayName?: string;
email?: string;
picture?: string;
};
// @public
export type Validators = {
isValidApiVersion(value: unknown): boolean;
@@ -509,9 +523,4 @@ export type Validators = {
isValidAnnotationValue(value: unknown): boolean;
isValidTag(value: unknown): boolean;
};
// Warnings were encountered during analysis:
//
// src/kinds/GroupEntityV1alpha1.d.ts:23:9 - (ae-forgotten-export) The symbol "GroupProfile" needs to be exported by the entry point index.d.ts
// src/kinds/UserEntityV1alpha1.d.ts:22:9 - (ae-forgotten-export) The symbol "UserProfile" needs to be exported by the entry point index.d.ts
```
packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts
+5 -7
View File
@@ -18,18 +18,16 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/Group.v1alpha1.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
export interface GroupProfileStatic {
displayName?: string;
email?: string;
picture?: string;
}
/**
* Backstage Group Profile.
*
* @public
*/
export type GroupProfile = Record<string, string> & GroupProfileStatic;
export type GroupProfile = Record<string, string> & {
displayName?: string;
email?: string;
picture?: string;
};
/**
* Backstage catalog Group kind Entity.
packages/catalog-model/src/kinds/UserEntityV1alpha1.ts
+5 -6
View File
@@ -18,17 +18,16 @@ import type { Entity } from '../entity/Entity';
import schema from '../schema/kinds/User.v1alpha1.schema.json';
import { ajvCompiledJsonSchemaValidator } from './util';
export interface UserProfileStatic {
displayName?: string;
email?: string;
picture?: string;
}
/**
* Backstage User Profile.
*
* @public
*/
export type UserProfile = Record<string, string> & UserProfileStatic;
export type UserProfile = Record<string, string> & {
displayName?: string;
email?: string;
picture?: string;
};
/**
* Backstage catalog User kind Entity.
packages/catalog-model/src/kinds/index.ts
+2
View File
@@ -33,6 +33,7 @@ export { groupEntityV1alpha1Validator } from './GroupEntityV1alpha1';
export type {
GroupEntityV1alpha1 as GroupEntity,
GroupEntityV1alpha1,
GroupProfile,
} from './GroupEntityV1alpha1';
export { locationEntityV1alpha1Validator } from './LocationEntityV1alpha1';
export type {
@@ -55,4 +56,5 @@ export { userEntityV1alpha1Validator } from './UserEntityV1alpha1';
export type {
UserEntityV1alpha1 as UserEntity,
UserEntityV1alpha1,
UserProfile,
} from './UserEntityV1alpha1';
plugins/org/src/components/Cards/Group/GroupProfile/GroupProfileCard.stories.tsx
+1 -1
View File
@@ -98,7 +98,7 @@ const extraDetailsEntity: GroupEntity = {
{
url: 'slack://user?team=T00000000&id=U00000000',
title: 'Slack',
icon: 'message',
icon: 'chat',
},
{
url: 'https://www.google.com',
plugins/org/src/components/Cards/Group/GroupProfile/GroupProfileCard.tsx
+3 -46
View File
@@ -37,13 +37,10 @@ import {
ListItemText,
Tooltip,
IconButton,
Divider,
} from '@material-ui/core';
import Icon from '@material-ui/core/Icon';
import AccountTreeIcon from '@material-ui/icons/AccountTree';
import EmailIcon from '@material-ui/icons/Email';
import GroupIcon from '@material-ui/icons/Group';
import LinkIcon from '@material-ui/icons/Link';
import EditIcon from '@material-ui/icons/Edit';
import CachedIcon from '@material-ui/icons/Cached';
import Alert from '@material-ui/lab/Alert';
@@ -55,8 +52,7 @@ import {
Link,
} from '@backstage/core-components';
import { alertApiRef, useApi } from '@backstage/core-plugin-api';
const staticProfileKeys = ['displayName', 'email', 'picture'];
import { LinksGroup, ProfileInfoGroup } from '../../Meta';
const CardTitle = (props: { title: string }) => (
<Box display="flex" alignItems="center">
@@ -99,11 +95,6 @@ export const GroupProfileCard = (props: { variant?: InfoCardVariants }) => {
const entityMetadataEditUrl =
group.metadata.annotations?.[ANNOTATION_EDIT_URL];
const profileKeys =
profile !== undefined
? Object.keys(profile).filter(key => !staticProfileKeys.includes(key))
: [];
const displayName = profile?.displayName ?? name;
const emailHref = profile?.email ? `mailto:${profile.email}` : '#';
const infoCardAction = entityMetadataEditUrl ? (
@@ -200,42 +191,8 @@ export const GroupProfileCard = (props: { variant?: InfoCardVariants }) => {
secondary="Child Groups"
/>
</ListItem>
{links !== undefined && <Divider />}
{links !== undefined &&
links.map(link => {
return (
<ListItem button component="a" key={link.url} href={link.url}>
{link.icon ? (
<ListItemIcon>
<Tooltip title={link.icon}>
<Icon>{link.icon}</Icon>
</Tooltip>
</ListItemIcon>
) : (
<ListItemIcon>
<LinkIcon />
</ListItemIcon>
)}
<ListItemText>{link.title}</ListItemText>
</ListItem>
);
})}
{profile !== undefined && profileKeys.length > 0 && <Divider />}
{profile !== undefined &&
profileKeys.length > 0 &&
profileKeys.map(key => {
const value = profile[key];
return (
<ListItem key={key}>
<ListItemText style={{ width: '25%', flexGrow: 0 }}>
{key}
</ListItemText>
<ListItemText>{value}</ListItemText>
</ListItem>
);
})}
<LinksGroup links={links} />
<ProfileInfoGroup profile={profile} />
</List>
</Grid>
</Grid>
plugins/org/src/components/Cards/Meta/LinksGroup.tsx
+69
View File
@@ -0,0 +1,69 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { EntityLink } from '@backstage/catalog-model';
import { IconComponent, useApp } from '@backstage/core-plugin-api';
import LanguageIcon from '@material-ui/icons/Language';
import {
ListItem,
ListItemIcon,
ListItemText,
Divider,
} from '@material-ui/core';
import React, { useCallback } from 'react';
const WebLink = ({
href,
Icon,
text,
}: {
href: string;
text?: string;
Icon?: IconComponent;
}) => (
<ListItem button component="a" key={href} href={href}>
<ListItemIcon>{Icon ? <Icon /> : <LanguageIcon />}</ListItemIcon>
<ListItemText>{text}</ListItemText>
</ListItem>
);
export const LinksGroup = ({ links }: { links?: EntityLink[] }) => {
const app = useApp();
const iconResolver = useCallback(
(key?: string): IconComponent =>
key ? app.getSystemIcon(key) ?? LanguageIcon : LanguageIcon,
[app],
);
if (links === undefined) {
return null;
}
return (
<>
<Divider />
{links.map(link => {
return (
<WebLink
key={link.url}
href={link.url}
text={link.title}
Icon={iconResolver(link.icon)}
/>
);
})}
</>
);
};
plugins/org/src/components/Cards/Meta/ProfileInfoGroup.tsx
+56
View File
@@ -0,0 +1,56 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { ListItem, ListItemText, Divider } from '@material-ui/core';
import React, { useMemo } from 'react';
const staticProfileKeys = ['displayName', 'email', 'picture'];
export const ProfileInfoGroup = ({
profile,
}: {
profile?: Record<string, string>;
}) => {
const profileKeys = useMemo(
() =>
profile !== undefined
? Object.keys(profile).filter(key => !staticProfileKeys.includes(key))
: [],
[profile],
);
if (profile === undefined || profileKeys.length === 0) {
return null;
}
return (
<>
<Divider />
{profileKeys.map(key => {
const value = profile[key];
return (
<ListItem key={key}>
<ListItemText style={{ width: '25%', flexGrow: 0 }}>
{key}
</ListItemText>
<ListItemText>{value}</ListItemText>
</ListItem>
);
})}
</>
);
};
plugins/org/src/components/Cards/Meta/index.ts
+17
View File
@@ -0,0 +1,17 @@
/*
* Copyright 2022 The Backstage Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
export * from './LinksGroup';
export * from './ProfileInfoGroup';
plugins/org/src/components/Cards/User/UserProfileCard/UserProfileCard.stories.tsx
+1 -1
View File
@@ -113,7 +113,7 @@ const extraDetailsEntity: UserEntity = {
{
url: 'slack://user?team=T00000000&id=U00000000',
title: 'Slack',
icon: 'message',
icon: 'chat',
},
{
url: 'https://www.google.com',
plugins/org/src/components/Cards/User/UserProfileCard/UserProfileCard.tsx
+3 -47
View File
@@ -33,15 +33,12 @@ import {
ListItemIcon,
ListItemText,
Tooltip,
Divider,
} from '@material-ui/core';
import EditIcon from '@material-ui/icons/Edit';
import EmailIcon from '@material-ui/icons/Email';
import GroupIcon from '@material-ui/icons/Group';
import PersonIcon from '@material-ui/icons/Person';
import LinkIcon from '@material-ui/icons/Link';
import Alert from '@material-ui/lab/Alert';
import Icon from '@material-ui/core/Icon';
import React from 'react';
import {
Avatar,
@@ -49,8 +46,7 @@ import {
InfoCardVariants,
Link,
} from '@backstage/core-components';
const staticProfileKeys = ['displayName', 'email', 'picture'];
import { LinksGroup, ProfileInfoGroup } from '../../Meta';
const CardTitle = (props: { title?: string }) =>
props.title ? (
@@ -80,11 +76,6 @@ export const UserProfileCard = (props: { variant?: InfoCardVariants }) => {
kind: 'Group',
});
const profileKeys =
profile !== undefined
? Object.keys(profile).filter(key => !staticProfileKeys.includes(key))
: [];
return (
<InfoCard
title={<CardTitle title={displayName} />}
@@ -139,43 +130,8 @@ export const UserProfileCard = (props: { variant?: InfoCardVariants }) => {
</ListItemText>
</ListItem>
{links !== undefined && <Divider />}
{links !== undefined &&
links.map(link => {
return (
<ListItem button component="a" key={link.url} href={link.url}>
{link.icon ? (
<ListItemIcon>
<Tooltip title={link.icon}>
<Icon>{link.icon}</Icon>
</Tooltip>
</ListItemIcon>
) : (
<ListItemIcon>
<LinkIcon />
</ListItemIcon>
)}
<ListItemText>{link.title}</ListItemText>
</ListItem>
);
})}
{profile !== undefined && profileKeys.length > 0 && <Divider />}
{profile !== undefined &&
profileKeys.length > 0 &&
profileKeys.map(key => {
const value = profile[key];
return (
<ListItem key={key}>
<ListItemText style={{ width: '100px', flexGrow: 0 }}>
{key}
</ListItemText>
<ListItemText>{value}</ListItemText>
</ListItem>
);
})}
<LinksGroup links={links} />
<ProfileInfoGroup profile={profile} />
</List>
</Grid>
</Grid>
storybook/.storybook/preview-head.html
-4
View File
@@ -1,4 +0,0 @@
<link
rel="stylesheet"
href="https://fonts.googleapis.com/icon?family=Material+Icons"
/>